add-skill

namespace	aiwg
name	add-skill
platforms	["all"]
description	Scaffold a new SKILL.md inside an existing addon or framework

Add Skill

Scaffold a new SKILL.md inside an existing addon or framework.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "I need a new skill" → scaffold skill in specified target
• "make a skill that does X" → derive name from description, prompt for target
• "add a natural language skill" → clarify name and target, then scaffold
• "skill for X" → derive name, prompt for target

Trigger Patterns Reference

Pattern	Example	Action
Named add	"add skill voice-apply --to voice-framework"	Scaffold directly
Description-driven	"create a skill that validates metadata"	Derive name=validate-metadata, prompt target
Interactive	"add skill --interactive --to aiwg-utils"	Guided design mode
Target omitted	"add skill my-skill"	Ask which addon or framework

Process

1. Parse Arguments

Extract from $ARGUMENTS:

• <name> — kebab-case skill name (required)
• --to <target> — addon or framework directory name (required; skills cannot be added to extensions)
• --interactive — enable guided design questions

If either <name> or --to is missing, ask before proceeding.

Note: Skills cannot be added to extensions. Extensions provide language/ecosystem-specific capabilities; skills require standalone, cross-cutting functionality.

2. Validate Target

Confirm the target addon or framework exists:

# Check addons
ls agentic/code/addons/<target>/

# Check frameworks
ls agentic/code/frameworks/<target>/

If target is an extension directory, explain the constraint and suggest using an addon instead.

3. Interactive Design (if --interactive)

Guide through skill design before generating:

1. Purpose: What does this skill do in one sentence?
2. Trigger phrases: What natural language phrases activate it?
   • Provide 3-5 examples covering common variations
3. Input: What does the skill need? (content, file path, parameters)
4. Process: What are the 3-7 execution steps?
5. Output: What does it produce? (transformed content, report, status)
6. Reference materials: Does it need supporting docs in references/?
7. Platform targeting: Which platforms should it deploy to?

4. Run Scaffolding

aiwg add-skill <name> --to <target>

5. Customize SKILL.md

The generated file needs these sections populated:

---
platforms: [all]
---

# Skill Name

[One-paragraph description of what the skill does and when it activates]

## Triggers

Alternate expressions and non-obvious activations:

- "<phrase>" → <what happens>
- "<phrase>" → <what happens>

## Trigger Patterns Reference

| Pattern | Example | Action |
|---------|---------|--------|
| <category> | "<example>" | <action> |

## Process

### 1. <Step Name>
[Description and any code blocks]

### 2. <Step Name>
[Description]

## Generated Structure (if applicable)

\`\`\`
<what files are created>
\`\`\`

## Output Format

\`\`\`
<what success output looks like>
\`\`\`

## Examples



: ""
: 
: 
: 



 @path/to/related/file — description

6. Add Reference Materials (if needed)

If the skill references supporting documentation:

mkdir -p <target>/skills/<name>/references/
# Create reference files as needed

7. Update Manifest

The CLI tool updates <target>/manifest.json. Verify:

{
  "skills": ["existing-skill", "<name>"]
}

Generated Structure

<target>/skills/<name>/
├── SKILL.md           # Main skill definition
└── references/        # Supporting documentation (optional)

Manifest updated: <target>/manifest.json

Output Format

Skill Created: <name>
─────────────────────
Location: <target>/skills/<name>/

Created:
  ✓ SKILL.md
  ✓ references/ (placeholder)

Manifest updated: <target>/manifest.json

Next Steps:
  1. Edit SKILL.md trigger phrases
  2. Write execution process steps
  3. Add reference materials (if needed)
  4. Test with natural language: "<trigger phrase>"

Examples

Example 1: Simple skill

User: "add skill lint-manifests --to aiwg-utils"

Action:

aiwg add-skill lint-manifests --to aiwg-utils

Result: agentic/code/addons/aiwg-utils/skills/lint-manifests/SKILL.md scaffolded with standard platform frontmatter and section stubs.

Example 2: Interactive skill with reference materials

User: "create a skill voice-apply --to voice-framework --interactive"

Process: Guided questions establish trigger phrases ("apply voice", "write in X voice"), process steps (identify voice, load profile, transform), and reference materials needed (voice profile templates).

Result: agentic/code/addons/voice-framework/skills/voice-apply/SKILL.md plus references/ directory.

Example 3: Framework skill

User: "scaffold skill requirement-tracer --to sdlc-complete"

Action:

aiwg add-skill requirement-tracer --to sdlc-complete

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/devkit-create-skill/SKILL.md — Devkit equivalent (interactive design)
• @$AIWG_ROOT/src/cli/handlers/scaffolding.ts — CLI handler implementation
• @$AIWG_ROOT/docs/cli-reference.md — Full CLI reference
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/ — Example skill definitions