Claude Code Skills Documentation: The Complete Developer Reference

I wasn't planning to dig into this today. I was just trying to understand why a colleague's ​​Claude Code​ setup behaved so differently from mine — and the answer turned out to be sitting in a folder I'd barely noticed.

What Claude Code Skills Documentation Covers

The phrase "anthropic claude code skills documentation" shows up in a lot of developer searches, and I think there's a reason for that: the skills system is genuinely spread across a few different surfaces, and it can take some time to piece together how they connect.

This article is based on Anthropic's official sources. But it tries to add something the docs alone can't fully offer — a slower layer of understanding, built from observation.

Where to find official docs

The canonical starting point is Anthropic's Claude Code skills reference, which covers the full skill lifecycle, SKILL.md format, and how Claude discovers and loads skills automatically.

For understanding how skills fit into the broader agent picture — including how they compare to Projects, MCP, and subagents — Anthropic published a useful blog post: Skills explained: How Skills compares to prompts, Projects, MCP, and subagents. That one helped me understand not just the ​what​, but the ​when​.

What this article adds beyond the official docs

The official documentation is accurate and well-structured. What it doesn't always capture is the pattern of small surprises — the moments where a skill doesn't trigger, or triggers too broadly, or where you realize a SKILL.md file and a CLAUDE.md file were doing slightly different jobs you'd conflated.

That's what I'm trying to trace here.

SKILL.md Format Reference

File location and naming

Every skill needs a SKILL.md file with two parts: YAML frontmatter (between --- markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked.

In Claude Code, skills live in .claude/skills/<skill-name>/SKILL.md inside a project, or in ~/.claude/skills/<skill-name>/SKILL.md for user-global skills. The folder name and the name field in frontmatter become the slash command — so .claude/skills/explain-code/SKILL.md with name: explain-code creates the /explain-code command.

Skills defined in .claude/skills/ within directories added via --add-dir are loaded automatically and picked up by live change detection, so you can edit them during a session without restarting. That behavior surprised me a little — I expected to need a restart.

Supported instruction types

Skills provide Claude with new capabilities through instructions and code. In practice, the markdown body can contain almost anything Claude can reason about: step-by-step procedures, style rules, output templates, domain terminology, reference content, and inline examples. Prefer using the imperative form in instructions.

One detail worth noting from the official skill-creator documentation: the description field is the primary triggering mechanism — include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body.

Format syntax and structure

The minimal SKILL.md looks like this:

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

# My Skill Name

[Instructions Claude follows when this skill is active]

At startup, the agent pre-loads the name and description of every installed skill into its system prompt. This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context.

Skills can also include supporting files — reference documentation, scripts, assets — in subdirectories. By moving form-filling instructions to a separate file, the skill author is able to keep the core of the skill lean, trusting that Claude will read that file only when needed.

Character and length limits

There's no hard character limit enforced on SKILL.md itself. The amount of context that can be bundled into a skill is effectively unbounded, because progressive disclosure means Claude loads additional files only when needed. But in practice, keeping SKILL.md focused on core instructions — under 500 lines — minimizes context bloat. Move detailed content to references/ and link to it.

What Claude Code Skills Can Instruct

Style and formatting preferences

Skills are well-suited to encoding output standards: how to structure a report, what tone to use, which headers to include. You can create a brand guidelines Skill that includes your company's color palette, typography rules, and layout specifications. When Claude creates presentations or documents, it automatically applies these standards without you needing to explain them each time.

Domain-specific knowledge

This is probably where skills are most useful in day-to-day work. Any domain that requires Claude to know something it wouldn't know from general training — your internal API conventions, a proprietary data format, a company-specific workflow — can be packaged into a skill and reused without repeating it in every prompt.

Tool use preferences

Skills can specify which tools to prefer, in what order, and under what conditions. When Claude invokes a skill, the system follows a simple workflow: it loads SKILL.md, expands it into detailed instructions, injects those instructions as new user messages into the conversation context, modifies the execution context (allowed tools, model selection), and continues the conversation with this enriched environment.

Output structure requirements

You can define very precise output templates inside a skill. The Anthropic skills GitHub repository has multiple examples showing how to anchor Claude to exact formats — report structures, commit message patterns, test file layouts.

What Skills Cannot Do

Execute code

SKILL.md is instruction content, not executable code. It tells Claude how to approach a task; it doesn't run anything on its own. Scripts inside a skill's /scripts directory can be invoked by Claude during task execution, but SKILL.md itself is just text.

Learn from errors

Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others. More fundamentally, a skill doesn't update itself based on what happened in a past session. The instructions are static until you edit them. I found this useful to remember — a skill is a snapshot of expertise, not a learning loop.

Share across agents or sessions automatically

Skills are scoped to the surfaces they're installed on. A skill created in Claude Code isn't automatically available in Claude.ai or through the API unless you upload it separately.

Skills vs. System Prompts vs. Project Rules vs. Memory

This is where I spent the most time getting confused. Here's how I understand the differences now:

Skills teach Claude how to do something. A Project might contain all the background on your product launch, while a skill could teach Claude your team's writing standards or code review process.

CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone. The key distinction from SKILL.md: CLAUDE.md loads ​always​; skills load ​when relevant​.

Claude Code's system prompt already contains around 50 individual instructions. Depending on the model, that's nearly a third of the instructions your agent can reliably follow — before rules, plugins, skills, or user messages. That number stayed with me. It changes how you think about how much to put in each layer.

FAQ

1 Where is the official Claude Code Skills documentation?

The primary reference is the ​Claude Code skills documentation​. For the broader Agent Skills standard — including how pre-built and custom skills work across Claude.ai and the API — see the Agent Skills overview on the Anthropic platform docs.

2 What format does SKILL.md use?

SKILL.md is a Markdown file with YAML frontmatter. The frontmatter requires two fields — name and description — which Claude reads at session startup to decide when to load the skill. The Markdown body contains the actual instructions Claude follows when the skill is invoked. Optional fields include context and agent for advanced execution control.

3 How long can a SKILL.md file be?

There's no enforced hard limit. Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable — skills let Claude load information only as needed, so the amount of context that can be bundled into a skill is effectively unbounded. That said, most practical guidance recommends keeping the core SKILL.md file under 500 lines and offloading detail to supporting files in references/.

I'm still not fully sure I've mapped all the edge cases here. The skill triggering behavior — when Claude decides a skill is relevant versus when it doesn't — is harder to predict than the format documentation suggests. Claude has a tendency to "undertrigger" skills — not to use them when they'd be useful. That's worth keeping in mind when writing your description field.

I'll keep watching how this settles.

Previous Posts:

• Discover how to properly add and configure MCP servers in your development environment
• Learn how Claude Code skills work and their practical implementation for AI agents
• Explore best practices for integrating Claude Code skills into your workflow
• Understand how the SKILL.md format affects Claude’s functionality and skill triggering
• Find out how to build, share, and extend custom Claude Code skills