creating-skills

name	creating-skills
description	Guide for creating Claude Code skills following Anthropic's official best practices. Use when user wants to create a new skill, build a skill, write SKILL.md, update an existing skill, or needs skill creation guidelines. Provides structure, frontmatter fields, naming conventions, and new features like dynamic context injection and subagent execution.

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)

Field	Required	Description
name	No	Display name. Defaults to directory name. Lowercase, hyphens, max 64 chars.
description	Recommended	What + when + capabilities. Max 1024 chars. Determines when Claude activates the skill.
allowed-tools	No	Tools Claude can use without asking permission when skill is active.
argument-hint	No	Autocomplete hint for arguments. Example: [issue-number]
disable-model-invocation	No	true to prevent auto-invocation (manual /name only).
user-invocable	No	false to hide from / menu (background knowledge only).
model	No	Model override when skill is active.
context	No	fork to run in isolated subagent context.
agent	No	Subagent type when context: fork. Built-in: Explore, Plan, general-purpose.
hooks	No	Lifecycle hooks scoped to this skill.

Invocation control matrix

Configuration	User can invoke	Claude can invoke
(defaults)	Yes	Yes
disable-model-invocation: true	Yes	No
user-invocable: false	No	Yes

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

Type	Purpose	Loaded into context?
scripts/	Deterministic operations, complex processing	No (executed via bash)
references/	Documentation Claude reads while working	Yes, on demand
assets/	Templates, images, fonts for output	No (copied/used in output)

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:

Variable	Value
$ARGUMENTS	Full argument string
$ARGUMENTS[0], $ARGUMENTS[1]	Individual arguments
$1, $2	Shorthand for $ARGUMENTS[N]

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:

Level	When to use	Example
High (text instructions)	Multiple valid approaches, context-dependent	"Analyze the code and suggest improvements"
Medium (pseudocode/scripts with params)	Preferred pattern exists, some variation OK	Script with configurable parameters
Low (specific scripts, few params)	Fragile operations, consistency critical	Exact sequence of API calls

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