// Guide for creating effective Claude Code skills. Use when designing, structuring, or building new skills with scripts, references, and assets.
Use tmux correctly from an agent — explicit pane targeting, safe-state verification, send verification, state distinction, and recovery. Use when Claude Code, Codex, GitHub Copilot CLI, or any TUI/REPL must keep state across commands.
Dispatch parallel subagents for independent tasks without shared state. Use when facing 2+ independent failures, debugging unrelated subsystems, or researching separate topics concurrently.
Create isolated git worktrees for feature work with safety verification. Use when starting feature branches that need isolation, running parallel agents in separate workspaces, or before executing implementation plans.
Closed-loop planning discipline for non-trivial changes. Use when creating implementation plans, reviewing plan completeness, or preparing PRs that require structured planning evidence.
Test-driven development discipline for any feature or bugfix. Use when implementing features, fixing bugs, or changing behavior — requires writing failing tests before implementation code.
Fetch up-to-date library documentation. Use when user asks about libraries, frameworks, or needs current API references/code examples.
| name | create-skill |
| description | Guide for creating effective Claude Code skills. Use when designing, structuring, or building new skills with scripts, references, and assets. |
Guide for creating effective skills for Claude Code.
The context window is a public good. Challenge each piece of information: "Does Claude really need this?" Prefer concise examples over verbose explanations.
Match specificity to task fragility:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description)
│ └── Markdown instructions
└── Optional Resources
├── scripts/ - Executable code (Python/Bash)
├── references/ - Docs loaded on demand
└── assets/ - Templates, images for output
name and description are the PRIMARY trigger mechanismscripts/ - For deterministic, repeatable code:
scripts/rotate_pdf.py
references/ - Documentation loaded as needed:
references/api-docs.md
references/schemas.md
assets/ - Files used in output (not loaded into context):
assets/template.docx
assets/logo.png
Three-level loading:
# PDF Processing
## Quick start
[core example]
## Advanced features
- **Form filling**: See [forms.md](references/forms.md)
- **API reference**: See [api.md](references/api.md)
bigquery-skill/
├── SKILL.md
└── references/
├── finance.md
├── sales.md
└── product.md
User asks about sales → only load sales.md
## Basic usage
[simple instructions]
**For advanced config**: See [advanced.md](references/advanced.md)
Ask:
For each example, identify:
mkdir -p .github/skills/my-skill
Frontmatter:
---
name: my-skill
description: [What it does AND when to use it. This is the trigger.]
---
Body:
/validate-skill .github/skills/my-skill
See .claude/references/skills-guide.md for all options:
| Field | Purpose |
|---|---|
name | Identifier (lowercase, hyphens) |
description | Primary trigger - when to use |
argument-hint | Autocomplete hint [arg] |
disable-model-invocation | Manual-only (true) |
user-invocable | Hide from menu (false) |
allowed-tools | Restrict tools |
context: fork | Run in subagent |
agent | Which subagent type |
create-report, review-prname field