Designs Claude Code skills with optimal descriptions, progressive disclosure, freedom levels, and token efficiency. Use for creating skills, improving descriptions, optimizing tokens, or debugging discovery.
From evolv3ainpx claudepluginhub evolv3ai/claude-skills-archive --plugin projectThis skill uses the workspace's default tool permissions.
README.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Status: 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