Imported from gswangg/create-skill (SKILL.md). Install upstream with npx skills add gswangg/create-skill. Copyright stays with the author.

Create a New Claude Code Skill

Create a skill based on the user's request. $ARGUMENTS is a plain text description of what the skill should do.

Skill Location

Create skills in the personal location by default unless the user specifies otherwise:

Required Structure

Every skill needs a SKILL.md file with YAML frontmatter:

---
name: skill-name
description: What this skill does and when Claude should use it
---

Instructions for Claude when this skill is invoked...

Frontmatter Fields

Include only the fields needed for the skill's purpose:

Core Fields

Invocation Control

By default, skills are invocable by both the user (via /skill-name) and Claude (automatically when relevant). Only change these when you have a specific reason:

Tool and Model Control

Subagent Execution

User Experience

Variable Substitutions

Use these in skill content:

(Remove backslashes in actual skill files)

Default to $\ARGUMENTS as a plain string. Only use positional $\0, $\1 etc. if the user specifically asks for structured arguments.

Dynamic Context Injection

Inject shell command output into skill content at load time. Write an exclamation mark immediately followed by the command wrapped in backticks. Example: to inject the current git branch, write exclamation-backtick-git branch --show-current-backtick (all as one token, no spaces around the backticks).

Supporting Files

For complex skills, keep SKILL.md under 500 lines and reference additional files:

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed documentation
├── examples.md        # Example outputs
└── templates/
    └── component.md   # Templates for Claude to use

Reference them in SKILL.md:

For API details, see [reference.md](reference.md)

Common Patterns

Pattern 1: Simple Slash Command

---
name: explain-code
description: Explains code with diagrams and analogies
---

When explaining code:
1. Start with an analogy
2. Draw ASCII diagram of the flow
3. Walk through step-by-step
4. Highlight common gotchas

Pattern 2: Command with Arguments (Plain String)

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
argument-hint: "issue number or description"
---

Fix GitHub issue based on: $\ARGUMENTS
1. Find the relevant issue
2. Understand requirements
3. Implement the fix
4. Write tests
5. Create a commit referencing the issue

Pattern 3: Background Knowledge Only (Exception Case)

Use this pattern only when the skill should never appear in the / menu - purely contextual knowledge that Claude applies automatically:

---
name: project-architecture
description: Architecture context for this codebase
user-invocable: false
---

This project uses:
- TypeScript with strict mode
- React for frontend
- PostgreSQL for data
- Our custom ORM in src/db/

When making changes, follow these patterns...

Pattern 4: Restricted Tool Access

---
name: safe-explore
description: Explore codebase without modifications
allowed-tools: Read, Grep, Glob
---

You can read and search files but cannot modify anything.
Answer questions about the codebase structure and content.

Pattern 5: Isolated Subagent Task

---
name: analyze-pr
description: Analyze a pull request in isolated context
context: fork
agent: Explore
---

PR context:
\!\`gh pr view\`
\!\`gh pr diff --name-only\`

Analyze this PR for:
- Code quality issues
- Potential bugs
- Missing test coverage
- Documentation needs

(Remove backslashes in actual skill files)

Pattern 6: Structured Arguments (Only When Explicitly Requested)

Most skills should use $\ARGUMENTS as a plain string. Only use positional args if the user specifically asks for them:

---
name: migrate
description: Migrate code from one pattern to another
argument-hint: "[file-pattern] [from] [to]"
---

Migrate files matching `$\0` from $\1 to $\2.

1. Find all matching files
2. Apply the migration pattern
3. Update imports
4. Verify no regressions

Creating the Skill

1. Create the directory at the chosen location
2. Write SKILL.md with appropriate frontmatter
3. Add supporting files if needed
4. Test by invoking with /<skill-name>