Creating skills

Guide for creating Claude Code skills following Anthropic's official best practices.

Project skill layout

This project uses a unified skills/ directory at the repo root, symlinked into tool-specific config directories:

<project-root>/
├── skills/                  # Canonical location for all skills
│   ├── code-review/
│   ├── creating-skills/
│   ├── dev/
│   └── git-commit/
├── .opencode/
│   └── skills -> ../skills  # Symlink for OpenCode
└── .codewiz/
    └── skills -> ../skills  # Symlink for Codewiz

This way a single set of skill definitions is shared across multiple AI coding tools.

Quick start

# 1. Create skill directory (in the project's unified skills/ dir)
mkdir -p skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <what it does>. Use when <triggers>. <capabilities>.
---

# <Skill title>

<instructions>
EOF

# 3. Add optional resources as needed
mkdir -p skills/<skill-name>/{scripts,references,assets}

# 4. Ensure symlinks exist (one-time setup per tool)
# ln -s ../skills .opencode/skills
# ln -s ../skills .codewiz/skills

SKILL.md structure

Frontmatter (YAML between --- markers)

Invocation control matrix

Description formula

<what it does>. Use when <triggers>. <capabilities>.

Include action verbs ("create", "handle"), user intent ("wants to", "needs to"), and domain keywords users would say.

Directory structure

skill-name/
├── SKILL.md          # Required: instructions (keep under 500 lines)
├── scripts/          # Optional: executable code (deterministic, token-efficient)
├── references/       # Optional: docs loaded into context on demand
└── assets/           # Optional: files used in output, NOT loaded into context
                      # (templates, images, fonts, boilerplate)

Progressive disclosure (3-level loading)

1. Metadata (name + description) - always in context (~100 tokens per skill)
2. SKILL.md body - loaded when skill triggers (keep under 5k words)
3. Bundled resources - loaded as needed by Claude

Reference supporting files from SKILL.md so Claude knows they exist. Keep references one level deep. For files over 100 lines, include a table of contents.

Scripts vs references vs assets

Only create scripts when they add value: complex multi-step processing, repeated code generation, deterministic reliability. Not for single-command wrappers.

Dynamic features

Context injection

Inject shell command output into skill content before loading:

## Recent commits
!`git log --oneline -5 2>/dev/null`

The output replaces the directive when the skill loads.

String substitutions

Pass arguments to skills invoked via /skill-name arg1 arg2:

Subagent execution

Run a skill in isolated context with context: fork:

---
name: deep-research
description: Research a topic thoroughly.
context: fork
agent: Explore
---

Degrees of freedom

Match specificity to the task's fragility:

Naming conventions

• Lowercase, hyphens between words, max 64 chars
• Styles: gerund (processing-pdfs), noun phrase (github-pr-creation), prefixed group (github-pr-*)

Important rules

• ALWAYS write descriptions that include WHAT + WHEN triggers + capabilities
• ALWAYS keep SKILL.md under 500 lines, split to references when approaching
• ALWAYS reference bundled files from SKILL.md so Claude discovers them
• NEVER duplicate info between SKILL.md and reference files
• NEVER create wrapper scripts for single commands
• NEVER include extraneous files (README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md)
• NEVER explain things Claude already knows (standard libraries, common tools, basic patterns)

References

• references/official_best_practices.md - Principles, anti-patterns, quality checklist, testing
• references/skill_examples.md - Concrete skill examples with new features