Building Custom Skills for Claude

I've been seeing a lot of posts lately about Anthropic's new resource on building skills for Claude. If you haven't come across it yet, they put out a 33-page PDF called The Complete Guide to Building Skills for Claude covering everything from folder structure to distribution. It's pretty thorough, but it also reads like product documentation and there's a fair bit to wade through.

So I figured I'd break it down into the parts that actually matter and walk through building a skill from scratch. If you've been using Claude for a while and keep re-explaining the same workflows, preferences, or domain knowledge every conversation, skills are basically how you fix that.

What Are Skills?

In short, a skill is a folder with instructions that teach Claude how to handle specific tasks or workflows. You teach it once, and it applies that knowledge automatically whenever it's relevant. No more repeating yourself every session.

At its core, a skill is just a folder with a SKILL.md file. No framework, no build step, no SDK. You write instructions in Markdown, slap some YAML frontmatter on top, and Claude picks it up. That's it.

Progressive Disclosure: How Skills Actually Load

The thing I found most interesting in Anthropic's guide is how skills actually get loaded into context. They don't just dump everything into Claude's context window at once. Instead, there's a three-level system:

Level 1: Frontmatter is always sitting in Claude's system prompt. It's just the name and description, enough for Claude to know when the skill should kick in. Costs almost nothing in tokens.

Level 2: SKILL.md body gets pulled in when Claude decides the skill is relevant to what you're asking. This is where your actual instructions, workflows, and examples live.

Level 3: Linked files like scripts, references, and assets are only accessed when Claude needs them mid-execution. Your detailed docs, validation scripts, and templates sit here until they're actually called for.

The upshot is that token usage stays low while Claude still has access to specialised knowledge when the situation calls for it.

Anatomy of a Skill

A single skill is just a folder. The structure looks like this:

code-review/
├── SKILL.md              # Required: main skill file
├── scripts/              # Optional: executable code
│   ├── validate.sh
│   └── process_data.py
├── references/           # Optional: documentation
│   ├── api-guide.md
│   └── examples/
└── assets/               # Optional: templates, icons
    └── report-template.md

Only SKILL.md is required. Everything else is optional and gets loaded progressively when needed.

Where Do Skills Live?

If you're building more than one skill, each one gets its own folder. You can keep them all in one place:

my-skills/
├── code-review/
│   ├── SKILL.md
│   └── references/
│       └── checklist.md
├── blog-post/
│   └── SKILL.md
└── sprint-planning/
    ├── SKILL.md
    └── scripts/
        └── fetch_velocity.py

Where you actually put these depends on how you're using Claude:

Claude.ai : Zip each skill folder individually (e.g. code-review.zip), then go to Settings > Capabilities > Skills and upload each one. You toggle them on or off from there.

Claude Code : Drop the skill folders into your Claude Code skills directory. Claude picks them up automatically.

Reference for Claude Code skills directory.

API : Skills can be attached to API requests via the container.skills parameter. See the API section further down for more on that.

Naming Rules

These are strict. Get them wrong and your upload will just fail:

• SKILL.md must be exactly SKILL.md (case-sensitive). Not skill.md, not SKILL.MD.
• Folder name must be kebab-case: code-review works, Code_Review doesn't.
• No README.md inside the skill folder. Documentation goes in SKILL.md or references/.
• No "claude" or "anthropic" in the skill name. Those are reserved.

The Frontmatter

Every SKILL.md starts with YAML frontmatter, and honestly this is the most important part of the whole skill. It's what determines whether Claude ever bothers loading it.

---
name: your-skill-name
description: What it does and when to use it. Include specific trigger phrases.
---

# Bad: too vague, Claude has no idea when to activate
description: Helps with projects.

# Bad: no trigger phrases, Claude can't tell when users need this
description: Creates sophisticated multi-page documentation systems.

# Good: specific action + clear trigger phrases
description: >
  Analyses pull requests for code quality, security issues,
  and adherence to team conventions. Use when user asks to
  "review this PR", "check this code", or "do a code review".

---
name: code-review
description: Analyses pull requests for code quality...
license: MIT
metadata:
  author: Your Name
  version: 1.0.0
---

code-review/
├── SKILL.md
└── references/
    └── checklist.md

---
name: code-review
description: >
  Performs systematic code reviews with a consistent checklist
  covering security, performance, readability, and best practices.
  Use when user asks to "review this code", "check this PR",
  "do a code review", or "look over these changes".
---

# Code Review Skill

## Instructions

When asked to review code, follow this process:

### Step 1: Understand the Context
- Ask what the code is meant to accomplish (if not obvious)
- Identify the language, framework, and relevant conventions
- Note the scope: full PR, single function, or specific concern?

### Step 2: Run the Checklist

For each category, note whether items pass, fail, or are not applicable.

**Security**
- No hardcoded secrets, API keys, or credentials
- Input validation at system boundaries
- No SQL injection, XSS, or command injection vectors
- Proper authentication and authorisation checks

**Performance**
- No unnecessary database queries or N+1 patterns
- Appropriate use of caching where applicable
- No blocking operations in async contexts

**Readability**
- Clear naming for variables, functions, and classes
- Functions do one thing and do it well
- No deeply nested conditionals (max 3 levels)

**Best Practices**
- Error handling covers failure modes
- No code duplication that should be abstracted
- Tests cover the critical paths

For the extended checklist, consult `references/checklist.md`.

### Step 3: Summarise Findings

Present findings grouped by severity:
1. **Critical** : must fix before merge
2. **Important** : should fix
3. **Suggestions** : nice to have
4. **Positive** : things done well

Always end with at least one positive observation.

## Examples

### Example 1: Quick function review
**User says:** "Can you review this function?"
**Actions:** Apply checklist to the provided code.
**Result:** Grouped findings with severity levels.

### Example 2: Full PR review
**User says:** "Review this PR for me"
**Actions:** Read all changed files, apply checklist across the full PR.
**Result:** Review with file-by-file and overall findings.

# Extended Code Review Checklist

## Security Deep Dive
- OWASP Top 10 considerations
- Dependency vulnerability checks
- Secrets scanning patterns
- CORS and CSP configuration

## Performance Patterns
- Database query optimisation techniques
- Caching strategies (in-memory, distributed, CDN)
- Lazy loading and pagination patterns

## Language-Specific Checks

### JavaScript/TypeScript
- Proper async/await error handling
- Memory leak patterns (event listeners, closures)
- Bundle size impact

### Python
- Type hints on public APIs
- Generator usage for large datasets
- Context managers for resources

### Step 1: Create Account
Call MCP tool: create_customer
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: setup_payment_method
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: create_subscription
Parameters: plan_id, customer_id (from Step 1)

### Phase 1: Design Export (Figma MCP)
1. Export design assets
2. Generate specifications

### Phase 2: Task Creation (Linear MCP )
1. Create development tasks
2. Attach asset links from Phase 1

### Phase 3: Notification (Slack MCP)
1. Post handoff summary to #engineering

### #Initial Draft
1. Fetch data via MCP
2. Generate first draft

### Quality Check
Run validation: scripts/check_report.py

### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

Should trigger:
- "Review this code for me"
- "Can you check this PR?"
- "Look over these changes"

Should NOT trigger:
- "Write a function that calculates tax"
- "What's the weather today?"
- "Help me set up Docker"