Agent Skills: how to build a local skill in Claude Code

Anthropic published the official documentation for Agent Skills, a format for packaging instructions, scripts, and reference materials that Claude starts using automatically when the user's request matches that capability. It isn't an isolated new feature: it's the formalization of a folder standard that already existed informally among those using Claude Code to automate repetitive tasks, now with naming rules, size limits, and a layered loading model described in detail by the company itself.

The real trick, according to the documentation, is progressive loading: a Skill doesn't get loaded into the context in full just because it exists. It's read in three levels, and each level costs a different price in tokens.

The three levels of a Skill

Every Skill is a folder with a mandatory SKILL.md file, which starts with a YAML front matter:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

This block is Level 1: it's always loaded in the system prompt, costs about 100 tokens per Skill according to Anthropic, and is the text against which Claude compares the user's request to decide whether to trigger the Skill or not. In practice, this means the quality of the description is the factor that decides whether the Skill fires or stays silent: it needs to say what the Skill does AND when to use it, because it's literally the only text available until the trigger happens.

Level 2 is the body of SKILL.md: instructions, workflows, code examples. It only enters the context when the description matches the request, and the documentation recommends keeping it under 5,000 tokens.

Level 3 consists of attached files: Python scripts, reference PDFs, database schemas. These are only read if the Level 2 instructions tell Claude to open them, and executable scripts never enter the context as code: Claude runs the script via bash and only receives the output. This means a Skill can bundle a 500-line validation script and cost zero context tokens until the moment it's actually executed.

Building a local Skill in Claude Code

The most direct way to test this in practice is through Claude Code, because there Skills are just files on disk, with no upload or API involved: you'd simply create the folder at ~/.claude/skills/ (personal) or .claude/skills/ at the project root (shared with the team via version control).

mkdir -p .claude/skills/changelog-writer
cd .claude/skills/changelog-writer

Inside it, a minimal SKILL.md following exactly the skeleton Anthropic documents:

---
name: changelog-writer
description: Generates changelog entries from the diff of recent commits. Use when the user asks to update CHANGELOG.md or summarize changes from a branch.
---

# Changelog Writer

## Instructions
1. Run `scripts/collect_diff.sh` to get the commits since the last tag.
2. Group by type (feat, fix, chore) using the Conventional Commits pattern.
3. Write the entry at the top of CHANGELOG.md, without removing history.

## Examples
Entry: "### Added\n- Added date filter support in the reports API"

And a script at scripts/collect_diff.sh that does the deterministic work (running git log, filtering by tag) without Claude having to generate that command on the fly. This is exactly the use case the documentation calls "deterministic operations at no context cost": the script runs, returns plain text, and only that text enters the conversation.

From there, it works automatically: within a Claude Code session, when asked something like "update the changelog with last week's commits," Claude recognizes the Skill's description, reads the SKILL.md, runs the script, and follows the instructions. There's no explicit command to "activate" the Skill, the trigger is entirely based on semantic matching between the request and the description, which makes writing that line the most sensitive point in the whole process.

Where this resembles (and doesn't resemble) MCP

Anyone who already builds MCP servers to give Claude access to databases, internal APIs, or third-party tools will notice an overlap in purpose, but the architecture differs in ways that matter when choosing which one to use.

An MCP server is a separate process, running a protocol, exposing tools with a strict JSON schema, and staying active (or at least declared) throughout the entire session. This has a cost: the tool definitions of every connected MCP server occupy context from the start to the end of the conversation, regardless of whether they're used or not. A Skill, by the design Anthropic describes, costs only the metadata (~100 tokens) until it's actually triggered, which makes room to install dozens of them without a context penalty.

On the other hand, MCP is an open, portable protocol: the same server works in Claude Desktop, in other MCP-compatible clients, and in third-party products. Skills, at least for now, don't sync across surfaces: a Skill created in Claude Code doesn't automatically appear in claude.ai, and a Skill uploaded via the API isn't available in claude.ai or vice versa. The documentation is explicit about this in the limitations section: the Skill has to be uploaded separately to each surface where it needs to work.

There's also a difference in execution environment. In Claude Code, a Skill has the same network access as any of the user's programs, which is convenient but also the most sensitive security point. A Skill running via the API, on the other hand, executes inside the code execution tool's container, with no network access and no real-time package installation, only what already comes pre-installed in that sandbox.

Where the promise breaks down

Anthropic's own documentation lists the points that undercut the "package once, use everywhere" pitch. The first one was already mentioned: Skills don't sync across claude.ai, the API, and Claude Code, so teams that use Claude across more than one surface end up replicating the same folder in three places, each with its own update cycle.

The second is security, addressed with a warning tone unusual for technical documentation: a malicious Skill can instruct Claude to run bash commands that don't match what the description promises, and the official recommendation is to treat third-party Skills as if installing unknown software, auditing SKILL.md, scripts, and any embedded network calls before using them. This weighs even more heavily in Claude Code, where the Skill inherits the developer's machine's full network access, unlike the API's isolated sandbox.

The third is the semantic trigger: since there's no explicit invocation command, a poorly written description simply won't fire the Skill, and the developer gets no error at all, Claude just proceeds without using it. This makes writing the description less trivial than it seems, and explains why Anthropic dedicates a separate guide just to this (the Skill authoring best practices cited in the documentation).

For those who already maintain working MCP servers, the Skill isn't an automatic substitute: it works well for procedural knowledge and deterministic scripts that today turn into a giant prompt repeated in every conversation, but it doesn't replace the need to expose a live external system, with authentication and state, which is the territory where MCP remains the more suitable piece.