Skip to content

fvadicamo/dev-agent-skills / plugins/skill-authoring/skills/creating-skills

creating-skills

Verified

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.

Quick start

# 1. Create skill directory
mkdir -p ~/.claude/skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
---

# <Skill title>

<Instructions for the skill workflow>
EOF

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

SKILL.md structure

Frontmatter (YAML between --- markers)

FieldRequiredDescription
nameNoDisplay name. Defaults to directory name. Lowercase, hyphens, max 64 chars.
descriptionRecommendedWhat + when + capabilities. Max 1024 chars. Determines when Claude activates the skill.
allowed-toolsNoTools Claude can use without asking permission when skill is active.
argument-hintNoAutocomplete hint for arguments. Example: [issue-number]
disable-model-invocationNotrue to prevent auto-invocation (manual /name only).
user-invocableNofalse to hide from / menu (background knowledge only).
modelNoModel override when skill is active.
contextNofork to run in isolated subagent context.
agentNoSubagent type when context: fork. Built-in: Explore, Plan, general-purpose.
hooksNoLifecycle hooks scoped to this skill.

Invocation control matrix

ConfigurationUser can invokeClaude can invoke
(defaults)YesYes
disable-model-invocation: trueYesNo
user-invocable: falseNoYes

Description formula

<What it does>. Use when <trigger phrases>. <Key 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

TypePurposeLoaded into context?
scripts/Deterministic operations, complex processingNo (executed via bash)
references/Documentation Claude reads while workingYes, on demand
assets/Templates, images, fonts for outputNo (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:

VariableValue
$ARGUMENTSFull argument string
$ARGUMENTS[0], $ARGUMENTS[1]Individual arguments
$1, $2Shorthand 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:

LevelWhen to useExample
High (text instructions)Multiple valid approaches, context-dependent"Analyze the code and suggest improvements"
Medium (pseudocode/scripts with params)Preferred pattern exists, some variation OKScript with configurable parameters
Low (specific scripts, few params)Fragile operations, consistency criticalExact 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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall