Agent Skills: Teaching Claude Your Workflows, Once and For All

Every organization has workflows that live in people's heads. The way you format a client report. The checklist your team runs before every deployment. The style guide that governs every piece of marketing copy. Getting Claude to follow these consistently has historically meant pasting the instructions into every conversation — and hoping the model pays attention.

Agent Skills change this entirely.

Skills are packages of instructions, scripts, and resources that Claude dynamically loads when they're relevant — teaching Claude your organization's specific ways of working, permanently. They're the difference between repeatedly explaining your preferences and having Claude just know them.

The Problem Skills Solve

Without skills, specializing Claude for your use case means one of three things:

1. System prompt bloat — Dumping all your guidelines into a massive system prompt that consumes tokens on every request, whether relevant or not
2. Repeated instructions — Pasting context into each conversation, which is tedious and easy to forget
3. Custom agents — Building dedicated agents with hardcoded knowledge, which don't compose well with other tools

Skills introduce a fourth option: progressive disclosure. Claude knows skills exist from brief metadata at startup, loads the relevant skill's full instructions only when needed, and can fetch additional detail on demand. You get specialization without bloat.

Anatomy of a Skill

Every skill is a folder with one required file: SKILL.md.

my-skill/
├── SKILL.md          # Required: instructions + frontmatter
├── reference.md      # Optional: supplementary detail
├── templates/        # Optional: supporting resources
└── scripts/          # Optional: executable code

The SKILL.md file uses YAML frontmatter followed by markdown instructions:

---
name: my-skill-name
description: A clear description of what this skill does and when Claude should use it
---

# My Skill Name

[Instructions Claude will follow when this skill is active]

## When to Use This Skill
- Situation A
- Situation B

## Process
1. Step one
2. Step two
3. Step three

Required frontmatter fields:

• name — Unique identifier (lowercase, hyphens only, e.g., quarterly-report)
• description — What the skill does and when Claude should activate it

That's it. Two fields and markdown. Skills are intentionally simple — and that simplicity is the point.

How Progressive Disclosure Works

Skills don't dump everything into Claude's context at once. Instead, information loads in layers:

Layer 1 — Metadata: At session startup, Claude sees only each skill's name and description from its frontmatter. This is just a few tokens per skill, so you can have dozens of skills available without bloating the context window.

Layer 2 — Core instructions: When Claude determines a skill is relevant to the current task, it reads the full SKILL.md. This might be 200–500 lines of detailed guidance.

Layer 3 — Supplementary resources: If the skill references additional files (like reference.md or templates), Claude fetches those on demand — only when needed for the specific task at hand.

Think of it like a well-organized manual: the table of contents is always visible, chapters load when you navigate to them, and appendices only open when referenced. Context is effectively unbounded because full detail only loads when needed.

Here's how this plays out in practice:

You: "Draft a case study for our Acme Corp engagement."

1. Claude scans available skills and sees: case-study-template | Generates branded case studies following our 4-section format with approved metrics
2. Recognizing relevance, Claude loads the full SKILL.md with your format guidelines
3. The skill references approved-metrics.md — Claude fetches it for the metrics section
4. Output matches your exact template, every time

Four Types of Skills

Not all skills come from the same source. Claude supports four distinct categories:

1. Anthropic Skills

Built and maintained by Anthropic for enhanced document handling. These go beyond simple markdown instructions to leverage specialized capabilities:

• Excel skill — Creates and edits .xlsx files with complex formulas, pivot tables, and charts
• Word skill — Generates .docx documents with proper formatting, styles, and tables
• PowerPoint skill — Builds .pptx presentations with layouts, slide masters, and animations
• PDF skill — Manipulates PDF files, fills forms, and extracts structured data

# Install in Claude Code
/plugin install document-skills@anthropic-agent-skills

2. Custom Skills

Skills you create for your own workflows. These require zero coding — if you can write markdown, you can write a skill. Common examples:

• A code-review skill that applies your team's specific standards
• A blog-post skill that enforces your brand voice and SEO checklist
• An incident-response skill that guides Claude through your on-call runbook

3. Organization-Provisioned Skills

Team and Enterprise plan owners can distribute approved skills organization-wide. When a team member opens Claude, the organization's skills are already available — no individual setup required. This is how you roll out consistent AI behavior at company scale.

4. Partner Skills

Pre-built skills from tools your team already uses:

• Notion — Creates structured Notion pages, databases, and projects
• Figma — Generates design specs and component documentation
• Atlassian — Creates Jira tickets and Confluence pages following your templates

Building Your First Custom Skill

Let's build a practical skill: a pr-description skill that generates consistent, high-quality pull request descriptions from your git diff.

Step 1: Create the skill folder

mkdir pr-description && cd pr-description
touch SKILL.md

Step 2: Write SKILL.md

Here's the full SKILL.md content for the pr-description skill:

---

pr-description/SKILL.md

---
name: pr-description
description: Generates a well-structured pull request description from a git diff or summary of changes. Use this when asked to write, draft, or create a PR description.
---

# PR Description Generator

When generating a PR description, always follow this exact structure:

## What Changed 1–3 sentence plain English summary. No jargon.

## Why Business or technical motivation. What problem does this solve?

## How Implementation approach. Key decisions made. What to look for in review.

## Testing

• Unit tests added/updated
• Integration tests pass
• Manual testing: [describe what you tested]

Style Guidelines:

• Use present tense: "Add authentication" not "Added authentication"
• Be specific about files changed: "Updates src/auth/jwt.ts to..."
• Quantify impact when possible: "Reduces API response time by ~40%"
• Flag breaking changes explicitly with ⚠️ Breaking Change:
• Don't list every commit message verbatim
• Don't add "This PR" at the start of sentences

---

Step 3: Install the skill

In Claude Code:

# Install from a local folder
claude skills add ./pr-description

# Or from a Git repository
claude skills add github:your-org/claude-skills#pr-description

In Claude.ai: Settings → Skills → Add custom skill → Upload the folder.

Step 4: Use it

> I just pushed a fix for the rate limiter bug. Generate a PR description.

Claude loads the pr-description skill and produces a description matching your exact template — every time, without reminders.

Skills with Code Execution

Plain markdown instructions handle most use cases. But some tasks are better done with code than with tokens. Skills can bundle executable scripts that Claude runs as tools:

excel-reporter/
├── SKILL.md
└── generate_report.py

The SKILL.md declares the script as a tool:

---
name: excel-reporter
description: Generates monthly sales reports as formatted Excel files with charts and pivot tables. Use when asked to create a sales report or export data to Excel.
tools:
  - type: python_script
    name: generate_excel
    path: ./generate_report.py
    description: Creates a formatted Excel report from JSON data
---

# Excel Reporter

When asked to generate a monthly sales report:

1. Ask for the data source (CSV file path or paste raw data)
2. Use the `generate_excel` tool to create the formatted file
3. Confirm the file was created and summarize key metrics found

Always generate reports with:
- Summary dashboard on Sheet 1
- Raw data on Sheet 2
- Month-over-month comparison chart
- Top 10 products table

The bundled Python script handles all the Excel formatting logic — openpyxl, charts, conditional formatting — deterministically, without relying on Claude to generate the implementation each time. The script handles what code is good at; Claude handles what language models are good at.

This pattern is powerful for:

• File format generation (Excel, PDF, DOCX)
• Data transformations with exact precision requirements
• API calls that need specific authentication flows
• Any task where reproducibility matters more than flexibility

Designing Skills That Actually Work

Writing an effective skill is more instructional design than software engineering. A few principles that separate skills Claude uses reliably from skills it ignores:

Name the trigger, not just the output

The description field is Claude's activation signal. Make it specific about when to activate:

# Too vague — Claude may not activate it:
description: Helps with writing tasks

# Specific — Claude knows exactly when to use it:
description: Generates technical blog posts in our developer-first style.
  Use when asked to write, draft, or create a blog post for our engineering blog.

Front-load the most critical constraints

Claude reads your skill top to bottom. Put non-negotiable rules first, examples and edge cases last. Don't bury "never include competitor names" on line 80.

Structure for scanning, not linear reading

Use headers, bullet lists, and code blocks. Claude processes structured information more reliably than dense paragraphs. Think documentation, not prose.

Keep skills focused

A quarterly-report skill is better than an all-writing skill. Focused skills load only when relevant, give clearer guidance, and are easier to maintain. If a skill is trying to do five things, split it into five skills.

Test your triggers

The most common failure mode is a skill that never activates. Verify by asking Claude: "What skills do you have available?" and "Would any of your skills help with [task]?" If the answer surprises you, rewrite the description field.

Installing Skills in Claude Code

Claude Code treats skills as first-class features with a full CLI:

# Browse the Anthropic marketplace
/plugin marketplace add anthropics/skills

# Install pre-built Anthropic skill bundles
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

# Add a skill from a local path
claude skills add ./my-skill

# Add a skill from GitHub
claude skills add github:org/repo#skill-folder

# List installed skills
claude skills list

# Remove a skill
claude skills remove my-skill-name

Project vs. user scope:

• Project skills live in .claude/skills/ — committed to your repo so the whole team gets them automatically
• User skills live in ~/.claude/skills/ — personal skills that follow you across every project

Project skills are the right choice for team workflows. User skills are right for personal preferences and habits you want everywhere.

Security: What to Watch For

Skills have real influence over Claude's behavior. Before installing — especially from external sources:

Read the SKILL.md before installing. Look for instructions that tell Claude to ignore safety guidelines, access external networks unexpectedly, or behave differently than the description claims.

Audit bundled scripts. Any Python or shell scripts in a skill run with your permissions on your machine. Review them like you'd review any third-party library.

Check external dependencies. A skill that imports requests and calls an unknown external URL is a red flag. Skills should be self-contained or explicitly transparent about network access.

Trust the source. Anthropic's official skills, your organization's provisioned skills, and Partner skills from named companies are safe to use. Anonymous skills from unknown repositories deserve the same scrutiny as any open-source dependency.

Real-World Use Cases

Here's what teams are building with skills today:

Engineering teams:

• code-review — Applies your specific linting rules and architecture standards
• pr-description — Consistent PR templates every time
• incident-postmortem — Structured postmortem documents following your blameless culture guidelines
• api-doc — OpenAPI spec generation in your house style

Marketing teams:

• blog-post — Enforces brand voice, SEO structure, and internal linking guidelines
• social-copy — Platform-specific character limits and tone for Twitter, LinkedIn, Instagram
• press-release — AP style, boilerplate language, and embargo formatting

Operations teams:

• weekly-report — Standardized format with required metrics sections
• client-email — Formality level, signature blocks, and escalation language
• vendor-evaluation — Consistent scoring rubrics and comparison matrices

The pattern is always the same: identify a task your team does repeatedly with consistent format requirements, encode those requirements once in a skill, and stop explaining yourself.

What's Coming

Anthropics has signaled a roadmap beyond the current skill system:

• Agents that write their own skills — Claude can identify its own capability gaps and propose new skills
• MCP + Skills integration — Skills that connect directly to external services through the Model Context Protocol
• Skill marketplace — Full lifecycle tooling for discovery, sharing, and versioning
• Collaborative skill editing — Teams building and refining skills together through Claude.ai

The underlying vision is making specialization democratic. Today, enterprise AI customization requires prompt engineers and fine-tuning. Tomorrow, a marketing manager should be able to teach Claude her brand guidelines in an afternoon — no engineering support required.

Getting Started

Skills are available today across:

• Claude.ai — Paid plans, via Settings → Skills
• Claude Code — Via claude skills add or the /plugin command
• Claude API — Programmatically through the Skills API
• Claude Agent SDK — First-class support for agent builders

Start small. Find one task your team repeats weekly that has a specific, documentable format — code reviews, client emails, release notes, incident postmortems. Write a SKILL.md for it. The format is simple enough that your first skill should take under 30 minutes.

Once Claude knows how you work, you stop explaining yourself and start shipping faster.

Resources

• What are Skills? — Anthropic Support
• Creating Custom Skills — Anthropic Support
• Official Skills Repository — GitHub
• Agent Skills Specification — agentskills.io
• Equipping Agents for the Real World — Anthropic Engineering