/devkit-create-skill

namespace: aiwg
name: devkit-create-skill
platforms: [all]
description: Enable interactive design mode
triggers:
  - "help me build a custom workflow"
  - "help me turn this repeated process into an AIWG workflow"
  - "decide whether this is a skill agent addon or docs recipe"
  - "skill architect"

Create AIWG Skill

Create a new skill that can be triggered by natural language patterns.

Understanding Skills

Skills differ from commands:

• **Commands**: Triggered by explicit `/command-name` invocation
• **Skills**: Triggered by natural language patterns (e.g., "apply voice", "validate writing")

Skills are ideal for:

• Capabilities users invoke conversationally
• Features that should "just work" without explicit commands
• Cross-cutting concerns that apply in many contexts

Process

1. Validate Parameters

Verify `$ARGUMENTS` contains:

• Skill name (kebab-case)
• `--to` target (addon or framework, NOT extension)

**Note**: Skills cannot be added to extensions because skills need standalone functionality.

Check target exists:

ls ~/.local/share/ai-writing-guide/agentic/code/addons/<target>/
# or
ls ~/.local/share/ai-writing-guide/agentic/code/frameworks/<target>/

2. Interactive Design (if --interactive)

Guide the user through skill design:

**Skill Purpose**: > What does this skill do? (e.g., "applies voice profiles to content", "validates code quality")

**Trigger Phrases**: > What natural language phrases should activate this skill? > Examples: > - "apply voice", "use voice", "write in <voice> voice" > - "validate code", "check quality", "review code" > - "format document", "clean up", "prettify"

**Input Requirements**: > What input does this skill need? > - Content to process > - Configuration parameters > - File paths

**Output Format**: > What does this skill produce? > - Transformed content > - Validation report > - Recommendations

**Reference Materials**: > Does this skill need supporting documentation? > - Style guides > - Validation rules > - Example outputs

3. Execute Scaffolding

Run the CLI scaffolding tool:

node ~/.local/share/ai-writing-guide/tools/scaffolding/add-skill.mjs \
  <name> \
  --to <target>

4. Generated Structure

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

5. Customize SKILL.md

The generated SKILL.md needs customization.

**REQUIRED frontmatter fields:**

• `name:` — skill slug (kebab-case)
• `description:` — **Mandatory.** Used by Claude Code for NL matching and required by Codex (Codex rejects any SKILL.md without a non-empty description). Never leave this blank.
• `version:` — semver string (e.g., `1.0.0`)
• `priority:` — **Mandatory.** Importance level: `critical`, `high`, `medium`, or `low`. Used by corpus gap reports and backlog tooling to surface work items. Never omit.

---
name: <skill-name>
description: <what this skill does — REQUIRED, non-empty>
version: 1.0.0
priority: medium
---

# <Skill Name>

## Trigger Phrases

Activate this skill when the user says:
- "<phrase 1>"
- "<phrase 2>"
- "<phrase 3>"

## Input

This skill expects:
- <input requirement 1>
- <input requirement 2>

## Execution Process

1. <Step 1>
2. <Step 2>
3. <Step 3>

## Output

This skill produces:
- <output 1>
- <output 2>

## Examples

### Example 1: <scenario>
**User**: "<example trigger>"
**Result**: <what happens>

### Example 2: <scenario>
**User**: "<example trigger>"
**Result**: <what happens>

6. Add Reference Materials

If the skill needs supporting documentation:

# Create reference files
touch <target>/skills/<name>/references/style-guide.md
touch <target>/skills/<name>/references/validation-rules.md

7. Update Manifest

The CLI tool automatically updates the manifest. Verify:

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

Output Format

Skill Created: <name>
─────────────────────

Location: <target>/skills/<name>/

Created:
  ✓ SKILL.md
  ✓ references/

Manifest updated: <target>/manifest.json

Next Steps:
  1. Edit SKILL.md to define trigger phrases
  2. Add execution process details
  3. Create reference materials (if needed)
  4. Test with natural language triggers

Examples

# Create skill in addon
/devkit-create-skill code-formatter --to aiwg-utils

# Create skill with interactive guidance
/devkit-create-skill voice-apply --to voice-framework --interactive

# Create skill in framework
/devkit-create-skill requirement-tracer --to sdlc-complete

Best Practices

1. **Clear trigger phrases**: Use natural, conversational language 2. **Multiple triggers**: Provide several ways to invoke the skill 3. **Specific execution**: Document exactly what happens when triggered 4. **Good examples**: Show realistic usage scenarios 5. **Reference materials**: Include supporting docs when needed

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/README.md — aiwg-dev addon overview
• @$AIWG_ROOT/docs/extensions/extension-types.md — Extension types including skill type
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference including add-skill command
• @$AIWG_ROOT/docs/extensions/creating-extensions.md — Guide to building custom extensions
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Concrete trigger phrase and loop termination requirements