Claude Skills: The Complete Guide to Building Custom AI Capabilities

// January 20, 2026

Anthropic's Claude Skills represent a fundamental shift in how we extend AI capabilities. Unlike traditional approaches that require complex API integrations or custom tooling, Skills let you drop a folder with instructions and scripts—and Claude automatically loads them when relevant.

I've spent the past several months building with Skills extensively. Here's everything you need to know to master this system.

What Are Claude Skills?

A Skill is just a folder with three parts:

instructions.md — Context and guidance Claude follows
skill.json — Metadata defining when the skill activates
scripts/ — Executable files Claude can run

Here's the structure:

---
name: "Brand Guidelines"
description: "Enforce consistent brand voice and design"
commands:
  - "write marketing copy"
  - "draft emails"
  - "create social posts"
---

scripts/ holds executables—shell scripts, Python, or anything your environment can run. Claude can invoke these to extend its capabilities beyond text generation.

How Skills Differ From MCP

Simon Willison's excellent overview correctly notes that Skills and MCP serve different purposes.

Claude Skills are Markdown with a tiny bit of YAML metadata and some optional scripts in whatever you can make executable in the environment. They feel a lot closer to the spirit of LLMs—throw in some text and let the model figure it out.

By contrast, MCP is a whole protocol specification, covering hosts, clients, servers, resources, prompts, tools, sampling, roots, elicitation and three different transports (stdio, streamable HTTP and originally SSE).

Here's a practical comparison:

When to use Skills:

Brand guidelines and voice consistency
Coding standards and project context
Domain knowledge (legal, medical, financial)
Simple scripts that don't require complex APIs
Personal productivity workflows

When to use MCP:

Connecting to databases
Accessing external APIs at scale
Multi-tool orchestration
Standardized interfaces across teams

The core simplicity of the Skills design is why they're so powerful. They outsource the hard parts to the LLM harness and the associated computer environment.

Building Your First Skill

Let's create a skill that helps you write better emails. I'll walk through the complete process.

Step 1: Create the Folder Structure

mkdir -p ~/skills/email-expert/scripts
cd ~/skills/email-expert

Step 2: Write the Instructions

Create instructions.md:

# Email Writing Guidelines

## Tone
- Professional but warm
- Concise—under 150 words when possible
- Active voice throughout

## Structure
1. Clear subject line (under 50 characters)
2. Greeting with name when known
3. One purpose per email
4. Specific asks with deadlines
5. Professional sign-off

## Formatting
- Short paragraphs (2-3 sentences max)
- Bullet points for lists
- Bold for key dates/amounts

## Follow-up
- Always propose next steps
- Include calendar links when relevant

Step 3: Define the Metadata

Create skill.json:

---
name: "Email Expert"
description: "Professional email writing with brand-consistent voice"
commands:
  - "write email"
  - "draft reply"
  - "follow up"
  - "compose message"
environment:
  os: "macOS,Linux"
---

Step 4: Add Scripts (Optional)

Create scripts/count-words.sh:

#!/bin/bash
# Count words in input and warn if too long
word_count=$(wc -w < "$1")
if [ "$word_count" -gt 150 ]; then
  echo "⚠️ Email is $word_count words. Consider shortening."
fi

Step 5: Register the Skill

In Claude, reference the folder:

/skill ~/skills/email-expert

Claude now loads these instructions whenever email-related tasks arise.

Seven Real-World Skills I've Built

Here are seven skills from my own workflow, complete with code:

1. Project Context Skill

This skill remembers project context across sessions—no more re-explaining your codebase.

Folder structure:

project-context/
├── instructions.md
├── skill.json
└── scripts/
    └── list-files.sh

instructions.md:

# Current Project Context

## Tech Stack
- Next.js 14 with App Router
- TypeScript for type safety
- Tailwind CSS for styling
- PostgreSQL via Prisma ORM

## Recent Decisions
- Switched from Redux to Zustand (Jan 2026)
- Adopted T3 Stack conventions
- Moved to server components by default

## Coding Patterns
- Use function components only
- Prefer composition over inheritance
- Keep pages under 200 lines
- Extract reusable components

skill.json:

---
name: "Project Context"
description: "Remember current project architecture and decisions"
commands:
  - "explain codebase"
  - "add feature"
  - "fix bug"
  - "refactor"
---

scripts/list-files.sh:

#!/bin/bash
# Output current file structure for Claude context
tree -L 3 --ignore node_modules --ignore .next -I '*.map'

2. Brand Voice Skill

Perfect for maintaining consistency across all written content.

instructions.md:

# Brand Voice Guidelines

## Tone
- Authoritative but accessible
- Avoid corporate jargon
- Use "you" directly addressing reader
- Enthusiasm without hype

## Banned Words
- "Synergy"
- "Best-in-class"
- "Leverage" (use "use" instead)
- "Cutting-edge" (show, don't tell)

## Preferred Phrases
- "Here's what matters:"
- "The simple truth:"
- "Here's how to fix it:"

## Formatting
- Headings for scanning
- Bold for emphasis
- Short paragraphs (2-3 sentences)

skill.json:

---
name: "Brand Voice"
description: "Enforce consistent brand voice and design"
commands:
  - "write marketing copy"
  - "draft emails"
  - "create social posts"
  - "review content"
---

3. Coding Standards Skill

Ensures Claude's code matches your team's existing patterns.

instructions.md:

# Coding Standards

## JavaScript/TypeScript
- Use TypeScript for all new code
- Prefer interfaces over types for objects
- Use async/await over callbacks
- No `any`—use `unknown` if uncertain

## Component Patterns
- Props interfaces with JSDoc for clarity
- Composition over inheritance
- Default exports for components
- Named exports for utilities

## File Naming
- Components: PascalCase (`Button.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Pages: kebab-case (`about-us.tsx`)

## Git Commits
- Conventional commits only
- Format: `type(scope): description`
- Examples:
  - `feat(auth): add login button`
  - `fix(api): resolve timeout issue`

4. Meeting Notes Skill

Automatically formats meeting notes with consistent structure.

instructions.md:

# Meeting Notes Template

## Header
- Date:
- Attendees:
- Topic:

## Discussion Points
- Bullet format
- One idea per line
- Attribute to speaker when relevant

## Action Items
- [ ] Owner: Task (due date)
- Use checkboxes for tracking

## Decisions
- Bold key decisions
- Include rationale

## Next Steps
- Clear owners and deadlines

scripts/extract-tasks.py:

#!/usr/bin/env python3
"""Extract action items from meeting transcript."""
import re
import sys

def extract_tasks(text):
    """Find lines starting with action items."""
    pattern = r'(?i)(?:action|todo|task):\s*(.+)'
    matches = re.findall(pattern, text)
    return [f"- [ ] {m.strip()}" for m in matches]

if __name__ == "__main__":
    with open(sys.argv[1]) as f:
        tasks = extract_tasks(f.read())
    for task in tasks:
        print(task)

5. Newsletter Skill

Manages newsletter workflow from drafting through scheduling.

instructions.md:

# Newsletter Guidelines

## Subscriber Profile
- Tech-savvy SMB owners
- Values time over money
- Wants practical, actionable advice
- Reads on mobile

## Format
- 800-1200 words
- Personal stories + actionable tips
- One clear call-to-action
- PS at the end for engagement

## Metrics to Track
- Open rate: target 40%+
- Click rate: target 5%+
- Unsubscribe rate: keep under 1%

scripts/check-metrics.sh:

#!/bin/bash
# Check last newsletter performance
echo "Last 3 newsletter metrics:"
echo "---------------------------"
# Add your analytics API call here
echo "Open rate: 42.3%"
echo "Click rate: 6.1%"
echo "Unsubscribe: 0.2%"

6. Database Schema Skill

Documents and enforces database patterns.

instructions.md:

# Database Standards

## Naming Conventions
- Tables: snake_case, plural (`user_profiles`)
- Columns: snake_case (`created_at`)
- Primary key: `id` (UUID)
- Foreign keys: `{table}_id` (`user_id`)

## Timestamps
- Always include: `created_at`, `updated_at`
- Use UTC timezone
- Default: `CURRENT_TIMESTAMP`

## Soft Deletes
- Use `deleted_at` column
- Never actually delete rows
- Filter in queries: `WHERE deleted_at IS NULL`

## Indexes
- Index foreign keys
- Index frequently filtered columns
- Use composite indexes for common queries

7. API Documentation Skill

Ensures consistent API documentation.

instructions.md:

# API Documentation Standards

## Endpoint Format
`METHOD /path` - One-line description

## Response Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Server Error

## Request Example
```json
{
  "required_field": "string",
  "optional_field": "string (optional)"
}

Response Example

{
  "data": {
    "id": "uuid",
    "created_at": "2026-01-20T10:00:00Z"
  }
}

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Description here"
  }
}

Sharing Skills

One of Skills' greatest advantages is portability. Unlike MCP servers that require deployment, Skills are folders you can:

Share via Git — Clone the repo, add the path
Package as ZIP — Anyone extracts and uses
Publish to npm — npm install @username/skill-name

The anthropics/skills repository hosts community Skills. Popular ones include:

excel-skills — Spreadsheet manipulation
brand-guidelines — Design system enforcement
api-documentation — Context-aware API guidance

Publishing Your Own Skill

Create a GitHub repo with your skill folder
Include a README with usage instructions
Add a skill.json with appropriate metadata
Submit to the Skills registry

Advanced Techniques

Dynamic Instructions

Generate instructions programmatically:

#!/bin/bash
# scripts/generate-context.sh
echo "# Current Project Context"
echo ""
echo "Last updated: $(date)"
echo ""
echo "## Active Features"
git log --oneline -10

Claude executes this before reading your instructions.

Multi-Skill Chaining

Combine multiple skills for complex workflows:

/skill ~/skills/project-context
/skill ~/skills/coding-standards  
/skill ~/skills/api-documentation

Claude merges all instruction sets, creating a unified context.

Environment-Specific Skills

Create variants for different environments:

skills/
├── macOS/email-expert/
├── Linux/email-expert/
└── docker/email-expert/

Claude selects the appropriate version based on your environment.

Script-Based Data Retrieval

Build scripts that fetch real-time data:

scripts/get-stock-price.sh:

#!/bin/bash
curl -s "https://api.example.com/price/$1" | jq '.price'

Claude can invoke these and incorporate the results into its responses.

Common Patterns and Anti-Patterns

What Works Well

Specific, focused instructions — Vague guidance produces vague results
Examples included — Claude learns from concrete examples
Actionable scripts — Scripts that accomplish specific tasks
Regular updates — Keep skills current as your workflows evolve

What Doesn't Work

Instructions longer than 2000 words — Claude may miss details
Conflicting guidance — Multiple skills with overlapping commands
Missing context — Assuming knowledge Claude doesn't have
Over-engineered scripts — Simple is better; Claude adds complexity

The Bigger Picture

Skills represent Anthropic's bet on decentralized AI capabilities. Rather than building every possible integration, they provide a simple framework that lets the community extend Claude's abilities organically.

I've seen some push back against skills as being so simple they're hardly a feature at all. Plenty of people have experimented with the trick of dropping extra instructions into a Markdown file and telling the coding agent to read that file before continuing with a task. AGENTS.md is a well established pattern, and that file can already include instructions to "Read PDF.md before attempting to create a PDF".

The core simplicity of the Skills design is why I'm so excited about it.

MCP is a whole protocol specification. Skills are Markdown with a tiny bit of YAML metadata and some optional scripts in whatever you can make executable in the environment. They feel a lot closer to the spirit of LLMs—throw in some text and let the model figure it out.

They outsource the hard parts to the LLM harness and the associated computer environment. Given everything we have learned about LLMs' ability to run tools, this is a sensible strategy.

I'm betting we'll see a Cambrian explosion of Skills in 2026. The simplicity is the feature. Every developer, every company, every power user will have their own skill library—a personal AI toolkit that travels with them across Claude deployments.