Claude Code Skills: The Developer Guide

Defining Claude Code Skills

A Claude Code skill is a directory containing a SKILL.md file with YAML frontmatter and instructions that Claude loads on demand. YAML frontmatter is a configuration block (metadata) placed between markers at the top of a text file. These skills extend the base capabilities of Claude by providing specialized playbooks, scripts, and documentation for specific coding tasks.

Skills reside on your local machine, typically in ~/.claude/skills/ or within a project-specific .claude/skills/ directory. Unlike global configuration files, skills are modular and portable. You can share them via version control or download them from community repositories to give Claude new 'powers' without manually prompting for every step.

The following file structure represents a standard skill layout:

skill-folder/
├── SKILL.md          # Core instructions and metadata
├── references/       # Optional deep-dive docs
└── scripts/          # Optional local executables

Takeaway: Skills are the primary way to give Claude procedural knowledge that only consumes context when relevant.

Why Skills Replace Static Prompts

Skills solve the context window overflow problem by ending the practice of 'stuffing the prompt.' Context window refers to the maximum amount of information an AI can process at once. Before skills, developers either pasted the same instructions repeatedly or bloated their CLAUDE.md files. This wasted tokens—basic units of text processing—on every single turn of the conversation.

Anthropic introduced skills to enable progressive disclosure. This design pattern ensures only the skill's name and description sit in the system prompt. The full instruction set (the 'body') only enters the conversation once the user triggers it. This makes skills much more efficient than large system prompts for complex tasks like flutter-development.

• Efficiency: Descriptions cost ~100 tokens; full bodies can be thousands.
• Focus: Claude is less likely to hallucinate when instructions are task-specific.
• Automation: Skills can bundle Bash scripts to perform real filesystem actions.

Takeaway: Stop using CLAUDE.md for procedures; move any multi-step checklist into a skill.

Mental Model and Architecture

Think of a skill as a 'lazy-loaded' tool that includes its own user manual. When you start Claude Code, it scans your skill directories and reads the metadata. Metadata is data that provides information about other data, such as a skill's name and usage triggers. It does not read the instructions yet.

The lifecycle follows four distinct phases:

1. Discovery: Claude reads names and descriptions into the system prompt.
2. Triggering: User intent matches the description, and Claude calls cat SKILL.md.
3. Execution: The body instructions guide Claude to use Bash tools or read reference files.
4. Persistence: The skill body stays in the conversation history until the session ends or is compacted.

+----------------+       +------------------+       +----------------+
|  Claude Code   | <---> | System Prompt    | <---> | SKILL.md       |
|  (Filesystem)  |       | (Name/Desc Only) |       | (Full Instructions)|
+----------------+       +------------------+       +----------------+
        |                                                |
        +--------------------[ Triggers Bash ]-----------+

Takeaway: The architecture prioritizes low-cost standby and high-depth activation.

The Smallest Working Skill

A functional skill requires only a SKILL.md file with a name and a description. Here is a minimal example for a skill that explains code using analogies. This demonstrates how to structure the frontmatter and the instruction block.

---
name: explain-with-analogies
description: Use this when the user asks how a specific function or file works.
allowed-tools: Read Bash
---

When explaining code, follow these steps:
1. Provide a real-world analogy (e.g., code is like a post office).
2. Use the `Read` tool to scan the file.
3. Output a 3-bullet summary of the logic.

To use this, save it to ~/.claude/skills/explainer/SKILL.md. You can then trigger it by asking: "How does the auth logic work?" Claude will recognize the intent, load the skill, and adopt the analogy-first persona.

Takeaway: You do not need complex scripts to start; a simple structured prompt is a valid skill.

Deep Dive: Tooling and Metadata

The allowed-tools Field

The allowed-tools field is a list in the YAML frontmatter that grants Claude pre-approval for specific actions. This prevents the 'Confirm execution?' interruption for common tasks. It does not restrict Claude to only those tools, but it streamlines the workflow for trusted scripts.

The skill-creator Meta-Skill

Anthropic provides an official skill called skill-creator. It acts as an agentic authoring assistant. You can prompt it with "Make a skill for triage of Linear issues," and it will generate the directory structure and evaluate the trigger descriptions for accuracy. This is the best way to handle linear agent skills generation.

Bundled Scripts

Skills can execute files in a scripts/ subfolder. These scripts run in the local shell. The important distinction is that Claude only sees the stdout—the standard text output—of the script, not the source code itself. This keeps the context window clean while performing heavy lifting like PDF parsing or complex Git operations.

Takeaway: Use allowed-tools to reduce friction and skill-creator to maintain manifest quality.

Developer Discovery: Real Mistakes

We assumed that skills uploaded to the Claude.ai web interface would sync to the local claude CLI. They do not. I spent forty minutes debugging a missing skill only to realize that local files and web uploads are entirely separate environments. You must manually move your SKILL.md files to the ~/.claude/skills folder for them to appear in your terminal.

Another common mistake was assuming skills would trigger in headless mode. Headless mode refers to running a command without an interactive session, such as claude -p 'fix my code'. We found that the trigger rate for skills in non-interactive mode is significantly lower unless you explicitly invoke the slash-command (e.g., /my-skill-name).

Finally, we initially ignored the security implications of the anthropic/ namespace. We discovered that any skill can claim an 'Anthropic' author tag in its YAML, but the folder path is what actually matters. Placing a community skill in the ~/.claude/skills/anthropic/ folder gives it perceived authority it may not have earned.

Takeaway: Treat local skills as standalone software installations; they do not sync and they require local trust.

Patterns: Wrong vs Right

Effective skill creation requires precise metadata and modular content. Use these patterns to ensure Claude triggers your skills correctly and stays within the token budget.

• ❌ Wrong: Writing a description that says "I do everything." Claude will ignore it for being too broad.
• ✅ Right: Writing "Use when the user wants to deploy a React app to AWS." Specific triggers win.
• ❌ Wrong: Pasting a 10,000-line documentation file directly into SKILL.md.
• ✅ Right: Putting the documentation in a references/ folder and telling the skill to read it only if needed.
• ❌ Wrong: Relying on Claude to 'remember' a skill from a previous turn during compaction.
• ✅ Right: Re-invoking the skill explicitly if it seems to have lost the thread of instructions.

Takeaway: Precision in your description is the difference between a tool that works and a folder of dead text.

Common Troubleshooting

The most frequent issue is the "silent failure" where a skill is installed but never runs. This is usually caused by a vague description. Anthropic's own skill-creator recommends being "a little bit pushy" in your description to force Claude's attention. If your skill isn't loading, check if the name uses only lowercase letters, numbers, and hyphens.

Another common bottleneck is permissions. If a skill requires the Bash tool but doesn't have it in allowed-tools, you will be prompted for every command. This breaks the automation flow. For skills involving drawio-diagrams-enhanced, ensure you have granted the necessary filesystem permissions in your /permissions settings.

Takeaway: If a skill doesn't trigger, rewrite the description to be more aggressive and explicit about its use case.

Performance and Token Usage

Skills are highly token-efficient at idle. Each installed skill consumes roughly 100-150 characters (not tokens) in the system prompt for its name and description. If you have 50 skills installed, you are only using about 5,000 characters of overhead—a tiny fraction of the Claude 3.5 Sonnet context window.

When a skill activates, the performance impact changes. Claude Code re-attaches the first 5,000 tokens of the most recent invocation of each active skill. There is a combined budget of 25,000 tokens across all skills. If you exceed this, Claude Code will prioritize the most recently used skills and truncate the rest. This ensures the model doesn't slow down during long coding sessions.

Takeaway: You can safely install dozens of skills without performance degradation, provided they aren't all active simultaneously.

Who Should Use Skills

Skills are designed for developers who have repeatable workflows that require more than just a single prompt. Consider building a skill if you meet these criteria:

• You have a project-specific deployment checklist or PR guide.
• You use a CLI tool that Claude frequently struggles to remember the syntax for.
• You need to bridge the gap between AI and your local terminal via scripts.
• You are working in a niche domain like flutter-development where custom linting rules apply.

Takeaway: If you've ever said "I wish Claude just knew how I like my commits formatted," you need a skill.

Community and Contrarian Voices

The developer community is divided on whether skills are a "game-changer" or just a rebrand of existing prompt engineering. On Hacker News, many developers praised the "progressive disclosure" aspect, noting it handles the token-cost issues of the Model Context Protocol. Simon Willison noted that skills are essentially "Markdown with a tiny bit of YAML," making them more accessible than building full MCP servers.

However, contrarian voices like Sibylline Software argue that skills introduce vendor lock-in. They suggest that because you cannot optimize the proprietary logic that selects skills, developers are at the mercy of Anthropic's hidden algorithms. Some Reddit users also complain that skills "do not sync across surfaces," making the developer experience fragmented between the terminal and the web browser.

Takeaway: The community loves the efficiency but remains wary of the lack of cross-platform synchronization.

The Verdict: Use or Skip

You should use skills for any procedure that you find yourself copy-pasting more than twice a week. They are the most efficient way to maintain a high-quality coding persona without paying the "context tax" of a giant system prompt. They are particularly powerful for local automation tasks that require shell access.

You should skip building a skill if your instructions are shorter than 200 words. In those cases, a standard CLAUDE.md file or a simple custom instruction is faster to maintain. Do not build a skill if you need an authenticated, real-time connection to a remote database—that is a job for an MCP server.

Takeaway: Skills are for procedures; MCP is for connections; CLAUDE.md is for facts.

When to Use Skills vs MCP

The choice between a skill and an MCP server depends on where the data lives and how it is accessed. MCP (Model Context Protocol) is a protocol—a set of rules for data exchange—that allows AI clients to connect to remote tools and resources. For a deep dive, see our what is mcp guide.

Reach for a skill when the answer is "I have a playbook." Reach for an MCP server when the answer is "I need to query my production database."

Takeaway: Skills and MCP are complementary; use skills to wrap MCP commands for a better UI.

The Future Ecosystem

Anthropic's vision involves skills and MCP servers converging. David Soria Parra of the Anthropic engineering team has suggested that future MCP servers will ship with their own skills. This allows the server to provide the "engine" (the tools) while the skill provides the "instruction manual" (how to use them effectively).

As the Agent Skills specification becomes more widely adopted, expect to see "Skill Hubs" that function like package managers. This will move skills from being local hacks to being version-controlled dependencies. In the long term, skills will likely be the primary way developers define the 'boundary' of what an agent is allowed to do on their machine.

Takeaway: We are moving toward a world where every major library ships with a SKILL.md file for AI assistants.

Frequently asked questions

Glossary

All sources

Primary

• Anthropic: Extend Claude with Skills
• Agent Skills Open Specification

Community

• Simon Willison on Claude Skills
• Community Tracking of Claude Skills

Critical and contrarian

• Sibylline: Claude Skills Considered Harmful

Documentation

• Anthropic API: Agent Skills Overview

Internal

• The Model Context Protocol Explainer
• Community Skill: Flutter Development
• Guide: Using MCP and Skills in Cursor