Skill Creator

This skill provides guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

Skills follow the Agent Skills open standard, with Claude Code extensions for invocation control, subagent execution, and dynamic context injection.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

Frontmatter Fields:

Example with all fields:

---
name: deploy-production
description: Deploy the application to production. Use after all tests pass.
argument-hint: [environment]
disable-model-invocation: true
allowed-tools: Bash(deploy:*), Read
context: fork
agent: general-purpose
---

String Substitutions

Skills support dynamic value substitution in the markdown content:

If $ARGUMENTS is not present in content, arguments are appended as ARGUMENTS: <value>.

Example:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Log progress to logs/${CLAUDE_SESSION_ID}.log

Dynamic Context Injection

The exclamation-backtick syntax runs shell commands before skill content reaches Claude. The command output replaces the placeholder.

Syntax: exclamation mark followed by backtick-wrapped command: EXCLAIM + BACKTICK command BACKTICK

Example skill content:

## PR Context
- Diff: EXCLAIM-BACKTICK gh pr diff BACKTICK
- Comments: EXCLAIM-BACKTICK gh pr view --comments BACKTICK
- Changed files: EXCLAIM-BACKTICK gh pr diff --name-only BACKTICK

Summarize this pull request...

(Replace EXCLAIM with the exclamation mark character and BACKTICK with the backtick character in real skills)

When this skill runs:

1. Each exclamation-backtick command executes immediately (before Claude sees anything)
2. The output replaces the placeholder in the skill content
3. Claude receives the fully-rendered prompt with actual data

This is preprocessing, not something Claude executes. Claude only sees the final result.

Invocation Control

By default, both users and Claude can invoke any skill. Two frontmatter fields control this:

When to use each:

• disable-model-invocation: true: For workflows with side effects (deploy, commit, send-message). Prevents Claude from triggering automatically.
• user-invocable: false: For background knowledge that isn't a meaningful command (e.g., legacy-system-context). Claude should know this when relevant, but /legacy-system-context isn't useful for users.

Subagent Integration

Add context: fork to run skills in isolation. The skill content becomes the subagent's prompt (no conversation history access).

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

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Agent options:

Note: context: fork only makes sense for skills with explicit instructions. Guidelines-only skills (e.g., "use these API conventions") receive no actionable prompt and return without meaningful output.

Skill Locations

Where a skill is stored determines who can use it:

When skills share the same name, higher-priority locations win. Plugin skills use plugin-name:skill-name namespace, so they cannot conflict.

Nested discovery: When editing files in subdirectories (e.g., packages/frontend/), Claude Code also discovers skills from nested .claude/skills/ directories. This supports monorepos where packages have their own skills.

Legacy commands: Files in .claude/commands/ still work with the same frontmatter. Skills are recommended since they support additional features like supporting files.

Bundled Resources (optional)

Scripts (scripts/)

Content Type: Code - Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, script code never enters context - only output does
• Key advantage: A 200-line script only costs ~20 tokens (the output), not 2000+ tokens (the code)
• Note: Scripts may still need to be read by Claude for patching or environment-specific