Creating Skills

Build reusable skills

Skill Creation Guide

Skills are reusable, auto-triggering capabilities that extend agent functionality. Unlike commands (user-invoked) or agents (orchestrator-launched), skills activate automatically when context matches.

Skill Anatomy

skills/
└── my-skill/
    ├── SKILL.md          # Required: Skill definition
    └── scripts/          # Optional: Implementation scripts
        └── my_script.py

SKILL.md Structure

REQUIRED frontmatter fields: `name` and `description` (non-empty). Codex rejects any SKILL.md without a non-empty `description:` field, and Claude Code uses it as the primary natural-language invocation signal. Tooling (scaffolder, SkillSmith generator, platform deployers) enforces this at runtime.

---
name: my-skill
description: Brief description (REQUIRED, non-empty — shown in skill catalog and used for NL matching)
triggers:
  - pattern: "regex or keyword"
    weight: 0.8
tags: [category, domain]
---

# Skill Title

## Purpose

What this skill does and when it activates.

## Execution Steps

1. Step one
2. Step two

## Output Format

Expected output structure.

Trigger Patterns

Skills activate based on trigger patterns matching user context:

Trigger TypeExampleUse Case
Keyword`"security review"`Direct phrase match
Regex`"(deployrelease) to prod"`Flexible matching
Context`"*.test.ts"` file in contextFile-based activation

Implementation Patterns

Prompt-Only Skills

Most skills need no code - the SKILL.md prompt is sufficient:

## Execution Steps

1. Read the target file using the Read tool
2. Analyze for patterns X, Y, Z
3. Report findings in structured format

Script-Backed Skills

For complex logic, add Python/Node scripts:

## Execution Steps

1. Run `scripts/analyze.py` with file path
2. Parse JSON output
3. Present findings to user

Script conventions:

  • Location: `skills/<skill-name>/scripts/`
  • Input: CLI arguments or stdin
  • Output: JSON to stdout
  • Errors: stderr with exit code

Creating a Skill

Via CLI

aiwg add-skill my-skill --to aiwg-utils

Via DevKit Command

/devkit-create-skill my-skill

Manual Creation

1. Create `skills/my-skill/SKILL.md` 2. Add frontmatter with name, description, triggers 3. Document execution steps 4. Optionally add scripts

Skill Categories

CategoryLocationPurpose
SDLC`sdlc-complete/skills/`Lifecycle workflows
Marketing`media-marketing-kit/skills/`Campaign operations
Utilities`aiwg-utils/skills/`Cross-cutting tools
Voice`voice-framework/skills/`Writing assistance
Testing`testing-quality/skills/`Test automation
Doc Intel`doc-intelligence/skills/`Document processing

Skill vs Command vs Agent

AspectSkillCommandAgent
InvocationAuto-trigger`/slash-command`Task tool
ScopeSingle capabilityUser workflowDomain expertise
ContextStatelessSessionIsolated
OutputInlineVariesReport back

Best Practices

1. Single responsibility: One skill, one purpose 2. Clear triggers: Avoid overlapping patterns 3. Graceful degradation: Handle missing context 4. Structured output: Consistent format 5. Documentation: Explain when/why skill activates

Testing Skills

# Validate skill structure
node tools/scaffolding/validate.mjs skills/<skill-name>

# Test trigger matching
aiwg skill-test <skill-name> "sample context"

Deployment

Skills deploy automatically with `aiwg use`:

aiwg use sdlc        # Deploys SDLC skills to .claude/skills/
aiwg use marketing   # Deploys marketing skills
aiwg use all         # Deploys all skills

Reference Design

The References section of a SKILL.md is not a bibliography — it is the primary mechanism for injecting context into the agent. An agent follows `@` refs to load rules, templates, schemas, and related skills as needed. The skill is the map; the corpus is the territory.

Thin skills with refs (preferred)

Avoid restating content that already exists in rules or other skills. Link instead:

## References

- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/anti-laziness.md — Never skip tests
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/executable-feedback.md — Run and verify before completing
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/testing/ — Test artifact templates
- @.aiwg/testing/ — Project test strategy and coverage baseline

Composite skills

A composite skill references multiple corpus documents to cover an orchestration that spans concerns. The skill contains minimal prose — it points to the docs that contain the detail:

# Issue Workflow Orchestrator

Coordinates issue listing, commenting, and closure.

## References

- @$AIWG_ROOT/.../skills/issue-list/SKILL.md — Fetch and filter issues
- @$AIWG_ROOT/.../skills/issue-comment/SKILL.md — Post structured status comments
- @$AIWG_ROOT/.../skills/issue-close/SKILL.md — Close resolved issues
- @$AIWG_ROOT/.../rules/context-budget.md — Parallel subagent limits

The agent opens whichever refs are relevant to the current step. Nothing loads until the agent follows a ref.

See `docs/development/corpus-navigation-guide.md` for the full context architecture and design patterns.

References