Claude Skills: Stop Repeating Instructions Forever

Problem: You type the same instructions into Claude Code every session. "Follow our brand guidelines." "Use our deployment process." "Check security patterns first." Context wasted. Time lost. Instructions forgotten.

Quick Win: Create your first skill right now:

.claude/skills/my-skill/SKILL.md

---
name: code-review
description: Reviews code for security and performance issues
---
 
# Code Review Process
 
1. Check for SQL injection vulnerabilities
2. Verify input validation exists
3. Confirm error handling patterns

That is a complete skill. Drop it in your project, and Claude automatically loads it when you ask for code review.

What Are Skills?

Skills are folders containing instructions that Claude discovers and loads dynamically. Think of them as specialized training manuals Claude references only when needed.

Unlike prompts (which disappear after each conversation) or MCP servers (which connect to external tools), skills teach Claude how to do things. They encode procedural knowledge: workflows, guidelines, checklists, and domain expertise.

Simon Willison noted this efficiency: "Each skill only takes up a few dozen extra tokens, with the full details only loaded in should the user request a task that the skill can help solve."

How Progressive Disclosure Works

Skills use a two-stage loading system that saves your context window:

Stage 1 - Metadata Only (~100 tokens): Claude sees skill names and descriptions. Just enough to know what is available.

Stage 2 - Full Instructions (when needed): Only when Claude determines a skill matches your task does it load full instructions—typically under 5,000 tokens.

my-skill/
├── SKILL.md              # Core instructions (loads when needed)
├── scripts/              # Automation scripts
├── references/           # Documentation Claude can read
└── assets/               # Templates and files

This architecture means you can have dozens of skills available without overwhelming Claude's working memory.

Skills vs Everything Else

Where do skills fit in Claude's ecosystem?

Key distinction: Projects say "here's what you need to know." Skills say "here's how to do things." MCP says "here's how to connect."

When to Create a Skill

The rule: If you type the same prompt across multiple conversations, create a skill instead.

Good candidates for skills:

• Brand guidelines and style rules
• Code review checklists
• Deployment procedures
• Security audit patterns
• Documentation templates
• Git commit conventions

Not ideal for skills:

• One-time requests
• Project-specific context (use Projects instead)
• External API access (use MCP instead)

Writing an Effective SKILL.md

Every skill needs three components:

---
name: my-skill
description: What it does and WHEN to trigger it
allowed-tools: "Read,Write,Bash"
---
 
# Clear Purpose Statement
 
## Step-by-Step Instructions
 
1. First action
2. Second action
3. Expected output

Critical: The description field determines when Claude activates your skill. Be specific about triggers: "When user requests code review" beats "Helps with code."

Pre-Built Skills from Anthropic

Anthropic maintains official skills you can use immediately:

• pdf: Extract text and tables from PDF documents
• docx: Create and edit Word documents with tracked changes
• xlsx: Manipulate Excel spreadsheets
• pptx: Generate PowerPoint presentations
• brand-guidelines: Apply consistent styling

Find them at github.com/anthropics/skills or create your own following their patterns.

Common Mistakes

Vague descriptions: "This skill helps with documents" will not trigger reliably. Be specific.

Overloaded instructions: Keep SKILL.md under 5,000 words. Use reference files for detailed documentation.

Missing boundaries: Tell Claude what the skill does NOT do. Prevents inappropriate activation.

Your Next Steps

1. Create one skill for your most repeated instruction
2. Test triggering with natural requests (not just explicit commands)
3. Iterate based on how it performs in real sessions
4. Explore context management to maximize your skill efficiency

Skills transform Claude from a general assistant into a specialized expert—without burning context tokens on repeated explanations. Your expertise becomes portable, reusable, and always available.