Skills
Instructions that tell the AI what to do -- the building blocks of every workflow
What is a Skill?
A markdown file with YAML frontmatter and instructions. Like giving a smart colleague a detailed checklist.
The Idea
A skill is a directory containing a SKILL.md file and optional supporting resources.
When you type /dx-plan, the AI reads the skill instructions and follows them step by step.
Skills live inside plugins and are auto-discovered by both Claude Code and Copilot CLI.
skills/dx-init/ ├── SKILL.md # Instructions (required) ├── scripts/ # Shell helpers │ ├── detect-env.sh # Environment detection │ ├── scaffold.sh # File scaffolding │ └── install-copilot-agents.sh # Agent template installer └── references/ # Context docs (optional) └── ... # Read by skill at runtime
More Than a Markdown File
Complex skills bundle supporting resources:
- scripts/ — Shell scripts the skill executes via
bash ${CLAUDE_SKILL_DIR}/scripts/…. Deterministic operations (file copying, env detection, scaffolding) that don’t need AI reasoning. - references/ — Context documents the skill reads at runtime. Design guidelines, fallback patterns, quality checklists. Keeps SKILL.md focused on instructions while offloading domain knowledge.
- assets/ — Templates and static files (report templates, wiki formats).
/dx-plan # AI reads skill, generates implement.md
Anatomy of a Skill
YAML frontmatter for metadata, markdown body for instructions.
--- name: dx-plan description: Generate an implementation plan from requirements allowed-tools: all --- # Implementation Plan Generator Read the requirements and codebase context, then produce a step-by-step implementation plan. ## Steps 1. Read explain.md from the spec directory 2. Read research.md for codebase context 3. Generate implement.md with numbered steps 4. Each step must include: file paths, what to change, and why 5. Save to .ai/specs/<id>/implement.md
Skills are instructions, not personas
Notice the skill says what to do, not who you are. A skill runs inline in your main conversation — the AI reads these instructions and follows them as itself. Compare this with agents, which define an isolated worker with its own identity, model, and tools.
Key Frontmatter Fields
| Field | Purpose | Example |
|---|---|---|
name | Slash command name | dx-plan |
description | What the skill does (shown in help) | Generate implementation plan |
argument-hint | Placeholder text for the argument | <ticket-id> |
allowed-tools | Tools the AI can use | all, or [read, edit, grep] |
disable-model-invocation | Skip AI reasoning (template-only) | true |
context: fork | Run in isolated subagent context | fork |
agent: | Run as a specific agent type | dx-code-reviewer |
Skill Categories in KAI
76 skills organized by workflow phase.
Requirements (/dx-req-*)
Fetch work items (ADO or Jira), explain requirements, research the codebase, share plans with the team.
/dx-req 2467362
Planning (/dx-plan)
Generate step-by-step implementation plans with file paths, code changes, and rationale.
/dx-plan
Execution (/dx-step-*)
Execute plan steps, verify changes, run build and lint checks after each step.
/dx-step-next
Review (/dx-pr-*)
Review PR diffs, post inline comments with severity levels, answer reviewer questions.
/dx-pr-review
Bug Fix (/dx-bug-*)
Triage bugs, find affected code, create fix branches, verify the fix works.
/dx-bug-fix 2451742
AEM (/aem-*)
Inspect AEM components, scan pages, verify dialog fields, capture screenshots.
/aem-component hero
Official Documentation
Deep-dive into skill authoring.