Design effective Claude Code skills with optimal descriptions, progressive disclosure, and error prevention patterns. Covers freedom levels, token efficiency, and quality standards. Use when: creating new skills, improving skill descriptions, optimizing token usage, structuring skill content, or debugging why skills aren't being discovered.
/plugin marketplace add jezweb/claude-skills/plugin install jezweb-tooling-skills@jezweb/claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdStatus: Production Ready Last Updated: 2026-01-09 Dependencies: None Reference: Anthropic's skill-creator
To scaffold a new skill, use the /create-skill command:
/create-skill my-new-skill
To design an effective skill, continue reading this guide.
Every token in your skill competes with conversation context. Be ruthlessly concise.
Ask for each paragraph:
references/ instead of main SKILL.md?Load information in layers:
| Layer | When Loaded | Target Size | Content |
|---|---|---|---|
| Metadata | Always | 40-55 tokens | name + description |
| SKILL.md | When triggered | <5k words | Instructions, patterns |
| Resources | As needed | Variable | scripts/, references/, assets/ |
Match instruction specificity to error probability:
High Freedom (text instructions)
Medium Freedom (pseudocode/patterns)
[CUSTOMIZE] placeholdersLow Freedom (specific scripts/templates)
The description is the most critical part - it determines if your skill gets discovered.
# Too short (loses context):
description: "A skill for Tailwind" # ❌ 25 chars
# Too long (wastes tokens):
description: "This comprehensive skill provides detailed knowledge..." # ❌ 500+ chars
# Just right:
description: |
Build modern UIs with Tailwind v4 + shadcn/ui. Covers CSS variable theming,
component installation, dark mode, and semantic color tokens.
Use when: setting up Tailwind v4, adding shadcn components, fixing theme issues,
or troubleshooting "Cannot find module" errors.
Paragraph 1: What you can build + key features (active voice) Paragraph 2: When to use + error keywords for discovery
# ❌ Bad: Passive, vague, no discovery keywords
description: |
This skill helps you with database operations. It provides patterns
for working with data and can be useful in many situations.
# ✅ Good: Active, specific, discoverable
description: |
Build type-safe database queries with Drizzle ORM and Cloudflare D1.
Covers schema definition, migrations, relations, and transaction patterns.
Use when: setting up D1 database, writing Drizzle schemas, debugging
"no such table" or "D1_ERROR" issues.
skills/my-skill/
├── SKILL.md # Main documentation (required)
└── README.md # Auto-trigger keywords (required)
skills/my-skill/
├── scripts/ # Executable helpers
│ └── setup.sh # Example: automated setup script
├── references/ # Extended documentation
│ └── api-guide.md # Loaded when user needs deep details
└── assets/ # Templates, images
└── config.json # Template files for output
scripts/: Deterministic tasks that must be exact
references/: Extended documentation too long for SKILL.md
assets/: Template files for output
---
name: lowercase-hyphen-case
description: |
[250-350 chars with "Use when:" section]
---
---
name: my-skill
description: |
[description - max 1024 chars]
allowed-tools:
- Bash
- Read
- Write
---
Note: allowed-tools is an optional field to restrict which tools Claude can use. The metadata: field with keywords: array is commonly used in this repository for improved discoverability, though it's not officially documented in the Anthropic spec. Fields like license: are informational but not functionally used by Claude Code.
processing-pdfs)# ❌ Won't be discovered
description: "Helps with authentication"
# ✅ Will be discovered
description: |
Implement authentication with Clerk - React components, middleware,
and Cloudflare Workers integration with JWT verification.
Use when: adding auth to React apps, protecting API routes, or
troubleshooting "clerk/backend" import errors.
# ❌ Claude already knows JavaScript basics
## Variables
Use `const` for constants and `let` for variables...
# ✅ Focus on what Claude might get wrong
## Critical: Cloudflare Workers Differences
- No `process.env` - use `env` parameter from fetch handler
- No Node.js `fs` module - use R2 or KV for storage
Skills are often triggered when users hit errors. Include common error messages:
description: |
...
Use when: troubleshooting "Cannot read properties of undefined",
"NEXT_REDIRECT" errors, or hydration mismatches.
# ❌ Too rigid (breaks if API changes)
Always call api.configure({ version: "2.1.0" }) first.
# ✅ Flexible with rationale
Configure the API client before making calls. The version should match
your installed package version (check package.json).
Skills should be tested in real projects, not just theoretically correct:
## Production Example
Tested in [Project Name]:
- Build time: 45 seconds
- Errors prevented: 6/6 documented issues
- Zero runtime errors after deployment
Compare tokens used with vs without skill:
| Metric | Without Skill | With Skill | Savings |
|---|---|---|---|
| Setup tokens | ~15k | ~5k | 67% |
| Errors hit | 2-3 | 0 | 100% |
| Iterations | 3-4 | 1 | 75% |
Ask Claude Code naturally:
"Help me set up [technology your skill covers]"
Claude should propose using your skill. If not:
Build a real project using only the skill's guidance:
./scripts/check-metadata.sh <skill-name>
Before committing a skill:
planning/claude-code-skill-standards.mdONE_PAGE_CHECKLIST.mdskills/tailwind-v4-shadcn/, skills/cloudflare-d1/# Create new skill
/create-skill my-skill-name
# Install skill
./scripts/install-skill.sh my-skill-name
# Verify metadata
./scripts/check-metadata.sh my-skill-name
# Check all skills
./scripts/check-all-versions.sh
# Generate marketplace manifest
./scripts/generate-plugin-manifests.sh my-skill-name
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.