| name | create-skill |
| description | Guide for creating a new Claude Code skill in this project. Use when asked to convert knowledge into a skill, create a slash command, or add a new skill file. |
Creating a Claude Code Skill
Skills live in .claude/skills/<skill-name>/SKILL.md. Each skill is a directory.
File Structure
.claude/skills/<skill-name>/
├── SKILL.md # Required — entrypoint with frontmatter + instructions
├── reference.md # Optional — detailed reference docs
├── examples.md # Optional — usage examples
└── scripts/ # Optional — bundled shell scripts the skill runs
└── <name>.sh
Skills with Scripts
Some skills bundle shell scripts that agents run as part of their procedure. This requires two locations for dual-tool support:
| Location | Purpose |
|---|
.claude/skills/<name>/scripts/<script>.sh | Claude Code — loaded relative to the skill |
.github/agent-scripts/<script>.sh | GitHub Copilot — accessible from repo root |
Both copies must remain byte-identical. When updating a script, update both locations simultaneously. Document this sync requirement in the SKILL.md.
When creating a skill with bundled scripts:
- Place the script in
.claude/skills/<name>/scripts/<script>.sh
- Copy it verbatim to
.github/agent-scripts/<script>.sh
- Note both locations in the SKILL.md body under a "Script reference" section
- Set
allowed-tools: Bash(sh *) in frontmatter so Claude can run the script without prompting
SKILL.md Frontmatter
---
name: skill-name
description: What it does and when to use it
allowed-tools: Bash(bun *) Read
disable-model-invocation: true
user-invocable: false
---
Key Frontmatter Fields
| Field | Use when |
|---|
description | Always — primary signal for when Claude auto-invokes |
allowed-tools | Skill needs to run specific commands without prompting |
disable-model-invocation: true | Skill has side effects (git push, deploy, etc.) — user must invoke manually |
user-invocable: false | Skill is background knowledge, not an action — hide from / menu |
argument-hint | Skill takes arguments — show hint in autocomplete |
context: fork | Skill should run in isolated subagent (long research, exploration) |
Dynamic Variables
$ARGUMENTS — everything typed after /skill-name
$0, $1, $2 — individual arguments by index
!`command` — shell command, executes before Claude sees the skill (output replaces it)
Example with dynamic context:
Current branch: !`git rev-parse --abbrev-ref HEAD`
Decision Guide
| Scenario | Approach |
|---|
| Project-specific CLI/build knowledge | Skill, no disable-model-invocation (let Claude auto-use) |
| Side-effect workflow (commit, deploy) | disable-model-invocation: true |
| Background reference only | user-invocable: false |
| Runs long searches or exploration | context: fork, agent: Explore |
After Creating a Skill
- Remove any redundant
.claude/<topic>.md file the skill replaces
- Update
.claude/memory/MEMORY.md to mention the skill exists
- Update
CLAUDE.md Additional Context section if the old file was referenced there
- Test by typing
/skill-name in Claude Code
Skill vs Memory File
- Skill: reusable procedure or reference that benefits from being a slash command, or that Claude should auto-invoke based on context
- Memory file (
.claude/memory/*.md): facts about decisions, history, or one-off project state that doesn't fit a repeatable pattern