/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

### Example 1: <scenario>

**User**: "<trigger phrase>"
**Extraction**: <what was parsed>
**Action**: <what runs>
**Result**: <what happens>

## References

- @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