The complete guide to Claude Code setup. 100+ hours saved. 370x optimization. Production-tested patterns for skills, hooks, and MCP integration.
Previous chapters covered skill mechanics – frontmatter fields, activation, budget. This chapter covers the philosophy of skill design: Anthropic’s principles for creating skills that are effective, maintainable, and context-efficient.
Purpose: Design better skills using Anthropic’s official design principles Source: Anthropic skill-creator guide (skills repo) + production experience Difficulty: Intermediate Time: 30 minutes to understand, ongoing application
“The context window is a public good. Skills share the context window with everything else. Default assumption: Claude is already very smart. Only add context Claude doesn’t already have.”
– Anthropic skill-creator guide
This principle should guide every skill design decision:
For each line in your skill, ask: “Would removing this cause mistakes?” If the answer is no, the line is wasting context.
Skills exist on a spectrum from “strict script” to “open guidance.” Choose the right level of freedom for the task:
When: Multiple valid approaches, creative tasks.
## Design Patterns
Consider the user's goals and project structure.
Choose the approach that best fits their architecture.
Common patterns include: [list]
The skill provides general guidance but trusts Claude’s judgment for specifics.
Examples: Frontend design, code review, architecture planning.
When: Preferred pattern exists but flexibility is needed.
## Deployment
1. Build the project
2. Run pre-deploy checks: `npm test && npm run lint`
3. Deploy using the project's deployment tool
4. Verify health endpoint responds
The skill defines the workflow but allows flexibility in implementation details.
Examples: Deployment workflows, testing procedures, migration paths.
When: Fragile or error-prone operations. A narrow bridge with cliffs on both sides.
## Database Migration
Run EXACTLY this command:
\`\`\`bash
pg_dump -h SOURCE --no-owner --exclude-table=audit_log | psql -h TARGET
\`\`\`
DO NOT modify the flags. DO NOT add --data-only. DO NOT skip --exclude-table.
The skill provides explicit commands with guardrails. Deviation causes failure.
Examples: Database operations, financial calculations, security-sensitive operations.
Think of Claude as exploring a path:
The description field is the only mechanism for skill activation. If the description doesn’t match the user’s intent, the skill won’t activate – no matter how good its content is.
description: "Deploy to GCP Cloud Run with traffic routing verification. Use when deploying to staging or production, checking deployment status, or routing traffic to new revisions."
Components:
| Mistake | Example | Problem |
|---|---|---|
| Too vague | “Helps with database stuff” | Matches everything, distinguishes nothing |
| Too technical | “PostgreSQL pgvector HNSW index management” | Users don’t say these words |
| Missing “Use when” | “Database operations for LIMOR AI” | No activation guidance |
| Internal details | “Uses pool.query with employee_id pattern” | Implementation, not activation |
Descriptions are capped at 1024 characters. Spend every character on activation quality, not feature lists. The skill BODY describes features – the description describes WHEN to use it.
For skills that overlap with others, add explicit “Do NOT use” guidance to prevent false activation:
description: "Debug production issues with decision tree routing. Use when encountering errors or investigating data gaps. Do NOT use for known patterns already covered by timezone, field-sync, or deployment skills."
When to add negative scope:
Pattern: Add “Do NOT use for/when…” after the “Use when…” clause.
Skills should load context progressively, not all at once:
description: "Deploy to GCP Cloud Run. Use when deploying to staging/production."
~100-200 characters. Loaded every message. Cost: minimal.
# Deployment Skill
## Quick Start
1. Build and deploy: `gcloud run deploy ...`
2. Route traffic: `gcloud run services update-traffic ...`
3. Verify: `curl https://service-url/health`
## Common Issues
- Traffic not routing → run update-traffic command
- Timeout → set --timeout=600
~200-500 lines. Loaded only when the skill activates. Cost: one-time per activation.
skill-directory/
SKILL.md # Level 2 (500 lines max)
references/
advanced-deployment.md # Level 3 (loaded via Read tool)
rollback-procedures.md # Level 3 (loaded via Read tool)
environment-parity.md # Level 3 (loaded via Read tool)
Unlimited size. Loaded only when the skill explicitly reads them. Cost: zero until needed.
| Level | When Loaded | Typical Size | Context Cost |
|---|---|---|---|
| 1 | Every message | ~150 chars | ~37 tokens/message |
| 2 | On activation | ~2,000 chars | ~500 tokens (once) |
| 3 | On demand | ~8,000 chars | ~2,000 tokens (rare) |
A skill with 3 reference files costs 37 tokens per message when inactive, not 2,500+.
Skills that reference executable scripts should NOT read the script source into context:
## Usage
Run `scripts/validate.sh --help` to see options.
Common commands:
- `scripts/validate.sh --quick` -- fast validation
- `scripts/validate.sh --full` -- comprehensive check
- `scripts/validate.sh --fix` -- auto-fix issues
DO NOT read the script source. Run with --help instead.
Why: A 200-line bash script = ~800 tokens of implementation details that Claude doesn’t need. The --help output gives Claude everything it needs to use the script correctly.
Rule: All scripts referenced by skills MUST support --help for self-documentation.
Keep skill directories clean. Only include files that serve a purpose:
skill-directory/
SKILL.md # Required: main skill file
references/ # Optional: detailed content
scripts/ # Optional: executable scripts
assets/ # Optional: templates, configs
Do NOT create these in skill directories:
README.md – SKILL.md IS the readmeINSTALLATION_GUIDE.md – installation belongs in SKILL.mdQUICK_REFERENCE.md – the skill IS the quick referenceCHANGELOG.md – use git history for changesTODO.md – use issue trackerWhy: Extra files in skill directories are noise. They don’t load automatically, aren’t referenced, and confuse maintenance. Every file should be either the skill itself or a supporting file explicitly referenced by the skill.
All reference files should be directly reachable from SKILL.md. No nested subdirectories:
# GOOD: One level deep
references/
advanced.md # SKILL.md links to this
troubleshooting.md
# BAD: Nested references
references/
advanced/
patterns/
edge-cases.md # Too deep, will be forgotten
Rule: If a file is more than one directory level from SKILL.md, it will never be found. Keep references flat.
For skills that generate complex output, add a verification step using a subagent:
## Post-Generation Verification
After generating output, spawn a verification subagent:
Task(subagent_type: "Explore",
prompt: "Verify the generated [output] is correct and consistent.
Check for: [specific things to verify].")
Why this works: The generating skill has been “staring at the code” and sees what it expects. A fresh subagent has no bias and catches obvious mistakes.
When to recommend: Multi-file changes, generated configurations, deployment scripts, database migrations.
| Skill Size | Lines | Action |
|---|---|---|
| Compact | <100 | Ideal for focused patterns |
| Standard | 100-300 | Most skills land here |
| Large | 300-500 | Use progressive disclosure |
| Over limit | >500 | MUST split into SKILL.md + references/ |
Claude Code enforces a 500-line limit on skill files. But even within 500 lines, prefer smaller skills that do one thing well.
.claude/rules/ insteadPrevious: 43: Claude Agent SDK