AS.
Back to Blog

How to Use Claude Skills: A Practical Guide for Developers

AIClaudeAnthropicAI AgentsProductivity

If you use Claude regularly, you've probably pasted the same instructions into a chat more times than you can count: your code review checklist, your company's writing style, the steps for generating a weekly report.

Claude Skills solve that. A Skill packages instructions, reference material and scripts into a folder that Claude loads only when it's relevant. You write it once, and Claude uses it whenever the task calls for it.

In this guide I'll cover what Skills are, how they work under the hood, and how to use them in the Claude app, Claude Code and the Claude API.

What is a Skill?

A Skill is simply a folder with a SKILL.md file inside it:

code-review/
├── SKILL.md          # Required: metadata + instructions
├── reference/        # Optional: longer docs Claude reads on demand
│   └── security-checklist.md
└── scripts/          # Optional: code Claude can run
    └── find-secrets.py

SKILL.md starts with a small YAML header, followed by normal Markdown instructions:

---
name: code-review
description: Reviews TypeScript and Next.js pull requests for bugs, security issues and readability. Use when the user asks for a code review, a PR review, or feedback on a diff.
---

# Code Review

## Process
1. Read the full diff before commenting.
2. Check correctness first, then security, then readability.
3. For security, follow reference/security-checklist.md.
4. Run scripts/find-secrets.py on changed files to catch leaked keys.

## Output format
- Group findings by severity: Critical, Important, Minor.
- For each finding, give the file, the line, the problem and a suggested fix.
- If there are no issues, say so in one sentence.

Two fields are required:

  • name: lowercase letters, numbers and hyphens, up to 64 characters. It can't contain the reserved words "anthropic" or "claude".
  • description: up to 1,024 characters. It should say what the Skill does and when to use it. This is the most important line in the whole Skill, because it's how Claude decides whether to load it.

How Skills load: progressive disclosure

The clever part of Skills is that they don't flood Claude's context window. They load in stages:

  1. Metadata, always loaded. At the start of a session, Claude only sees each Skill's name and description, roughly 100 tokens per Skill. You can install many Skills without slowing anything down.
  2. Instructions, loaded when relevant. When your request matches a description, Claude reads the full SKILL.md body.
  3. Resources, loaded only if needed. Extra files like reference/security-checklist.md are read only when the instructions point to them. Scripts are executed, so only their output uses context, not their source code.

This means a Skill can bundle long API docs, templates or datasets at almost no cost until they're actually needed.

Using Skills in the Claude app

In the Claude web and desktop apps (paid plans), Skills work out of the box:

  • Pre-built Skills. Anthropic ships Skills for creating and editing Word (docx), Excel (xlsx), PowerPoint (pptx) and PDF files. Just ask Claude to "make a slide deck from these notes" and it uses them automatically.
  • Code execution must be on. Skills run inside Claude's code execution environment, so make sure code execution is enabled in Settings.
  • Custom Skills. Zip your Skill folder and upload it in the Skills section of Settings. The zip should contain the folder itself (code-review.zip → code-review/SKILL.md), not a loose SKILL.md at the root.

Custom Skills you upload in the app are private to your account.

Using Skills in Claude Code

Claude Code is where Skills really shine for developers, because they live right in your filesystem.

Where to put them:

  • Personal Skills (available in every project): ~/.claude/skills/<skill-name>/SKILL.md
  • Project Skills (shared with your team via git): .claude/skills/<skill-name>/SKILL.md
  • Plugin Skills: installed from a plugin marketplace with /plugin

How they're used:

  • Automatically: Claude loads a Skill when your request matches its description. Ask "review my changes" and the code-review Skill kicks in.
  • Manually: type /code-review to invoke it directly.

You can control this with optional frontmatter fields:

---
name: deploy-production
description: Deploys the app to production. Use only when the user explicitly asks to deploy.
disable-model-invocation: true
---
  • disable-model-invocation: true means only you can trigger it with /deploy-production. Use this for anything with side effects, like deploys, database migrations or sending messages.
  • user-invocable: false does the opposite: it hides the Skill from the slash menu, so it acts as background knowledge Claude applies on its own.
  • allowed-tools pre-approves specific tools while the Skill runs, so you aren't prompted for every step.

A good first project Skill: commit your team's conventions (testing rules, API patterns, PR format) to .claude/skills/ so every developer's Claude follows the same playbook.

Using Skills with the Claude API

On the API, Skills run inside the code execution container. You pass the Skills you want in the container parameter and enable the code execution tool:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    betas=["code-execution-2025-08-25"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[
        {
            "role": "user",
            "content": "Create a monthly budget spreadsheet with a chart of expenses by category.",
        }
    ],
)

A few things to know:

  • Pre-built Skills use "type": "anthropic" with IDs like pptx, xlsx, docx and pdf.
  • Custom Skills are uploaded once through the Skills API (/v1/skills). You then reference them with "type": "custom" and the returned skill ID.
  • Generated files (the spreadsheet above, for example) are saved in the container, and the response includes file IDs you can download with the Files API.
  • The API sandbox has no network access and can't install packages at runtime, so Skill scripts must only use the libraries already available there.

The API surface changes quickly, so check the Skills guide in Anthropic's docs before shipping to production.

Best practices for writing Skills

These come from Anthropic's own guidance and from what has worked for me:

  1. Write a specific description. Include what it does, when to use it, and the words people actually say. "Helps with documents" is too vague; "Extracts tables from PDF invoices. Use when the user uploads an invoice or asks about invoice data" works.
  2. Write in the third person. "Reviews pull requests…", not "I can help you review…"
  3. Keep SKILL.md short. Aim for under 500 lines. Claude is already smart; include only what it wouldn't know, like your conventions, your edge cases and your output format.
  4. Move details into reference files. Link them directly from SKILL.md, one level deep, so Claude reads only what the current task needs.
  5. Use scripts for deterministic work. Validation, parsing and formatting are more reliable as a script Claude runs than as instructions Claude follows.
  6. Pick defaults. Don't list five ways to do something; choose one and explain when to deviate.
  7. Test with real tasks. Try the Skill on actual requests, watch where Claude gets confused, and refine. Test with the models you'll really use; a smaller model may need more explicit instructions.
  8. Use forward slashes in paths, even on Windows.

Stay safe: treat Skills like software

A Skill can contain instructions and executable code, so installing one is like installing a program:

  • Only use Skills you wrote or that come from sources you trust.
  • Read every file in a third-party Skill before installing it, especially the scripts. Look for unexpected network calls or file access.
  • Be careful with Skills that fetch external content, since fetched text can contain malicious instructions (prompt injection).

Skills vs MCP vs CLAUDE.md vs subagents

These features are easy to confuse. Here's how they differ:

  • Skills package expertise and workflows: how to do a task well. They load on demand.
  • MCP servers connect Claude to external systems: GitHub, Slack, databases, internal APIs. They give Claude new capabilities, and a Skill can teach Claude how to use them well.
  • CLAUDE.md holds project instructions loaded at the start of every session in Claude Code. Use it for short, always-relevant rules; move longer, task-specific guidance into Skills.
  • Subagents run separate Claude instances with their own context, useful for parallel or isolated work.

A simple rule of thumb: if you keep pasting the same instructions into Claude, make it a Skill. If Claude needs access to a system it can't reach, add an MCP server.

Where to start

  • Browse Anthropic's open-source examples at github.com/anthropics/skills.
  • Turn your most-repeated prompt into your first Skill today.
  • In Claude Code, add a project Skill for your team's conventions and commit it.

Skills are one of the easiest ways to make Claude behave like a teammate who already knows how you work. If you'd like help designing Skills or AI workflows for your team, get in touch.