Claude Code Skills Deep Dive (0): From Repeated Prompts to Callable Capabilities

TL;DR: A Skill packages instructions, checklists, and multi-step workflows into an on-demand capability. Claude can discover it from its name and description, load the full instructions when they matter, and then use existing tools to do the work. A Skill participates in capability selection, but it is not a new atomic executor.

When preparing a release, you may find yourself telling Claude the same thing again:

First check the working tree, then run the tests, prepare a changelog, verify the version number, and list the files that would be released. Do not actually publish anything until I confirm. 

This is not a fact that applies to every task in a project, so putting it in CLAUDE.md would make unrelated sessions carry an occasional procedure. Nor is it one atomic tool action: it involves checking Git state, running tests, reading a changelog, and summarizing risks in a deliberate order. It is a reusable way of working that otherwise has to be restated in each conversation.

That is the problem a Skill solves: how can operational knowledge persist without entering every task's context?

Save the workflow as a folder

Put the release procedure in a directory called release-check:

release-check/ └── SKILL.md 

The file has two parts:

--- name: release-check description: "Check whether a version is ready to release; use when preparing a release." --- 1. Inspect the working tree. 2. Run tests and a build. 3. Check the version number and changelog. 4. Summarize risks and wait for user confirmation. 

The frontmatter fields name and description are metadata: a compact index entry that helps Claude recognize when this capability is relevant. The Markdown after the frontmatter is the instructions: the actual workflow Claude follows when the Skill is used. The Agent Skills specification defines this basic directory-and-SKILL.md shape; Claude Code's Skills guide explains how Claude Code discovers and invokes it.

The distinction is about timing. The description can be available for selection without loading the entire procedure. Once the task matches, Claude reads the full Skill body. Supporting files can be opened later, only if needed. This staged approach is called progressive disclosure. It keeps a large library of Skills practical, although metadata itself still has a context cost—descriptions should be useful and concise.

Selection resembles tool selection—but execution does not

If the user asks, “Is this version ready to release?”, Claude can decide whether release-check matches the request. The user can also invoke it explicitly with /release-check. This resembles tool selection in one respect: the model sees a capability's name and purpose, then decides when it applies.

It does not make a Skill the same thing as a tool. A tool has an executable operation behind it: Read reads a file; Bash runs a command. A tool call goes to a runtime and returns a result. Loading release-check instead gives Claude a set of instructions. Claude still uses existing tools to inspect the repository, run tests, and read the changelog. The Skill governs sequence, judgment, and stopping conditions; the tools perform the individual actions.

That is also why a Skill is not merely another name for CLAUDE.md. The latter carries standing project guidance into a session. A Skill is a discoverable, reusable candidate whose detailed instructions are loaded when relevant.

Tools turn “I can describe an action” into “I can perform an action.” Skills organize those actions into a reliable method for a recurring class of work.

The folder can carry more than instructions

Four Markdown steps are already more reusable than a prompt pasted into chat. But the directory can also contain supporting resources:

release-check/ ├── SKILL.md ├── references/version-policy.md ├── scripts/validate-version.sh └── assets/release-report.md 

references/version-policy.md records the project's versioning rules. Claude reads it when deciding whether a change warrants a major release, not during every task. scripts/validate-version.sh turns a deterministic format check into executable logic instead of asking the model to improvise that check each time. assets/release-report.md gives the final report a consistent template.

The main instructions answer how to carry out this task now. A reference file supplies what the agent should know when a particular question arises. Both can enter context on demand, but they serve different purposes. The Skills guide documents supporting files and scripts; the next article in this series will look more closely at the folder format.

What happens after installation?

Several questions remain:

• Discovery: How does Claude know this Skill exists?
• Activation: Is typing /release-check the same path as Claude choosing it from the description?
• Execution: Do the instructions run in the current conversation, or can they be delegated to a separate agent that returns only a summary?
• Governance: Who can distribute the Skill, invoke it, and authorize the tools it uses?

These questions lead to a broader design rule: stable facts belong in standing guidance, atomic actions belong in tools, and reusable operational knowledge belongs in Skills. The series will reach that boundary in its conclusion. First, it will follow the lifecycle of a Skill like release-check, rather than translating documentation field by field.

Three layers, three costs

The folder structure is not merely a way to organize files. It determines when each piece becomes visible:

If the description is vague, Claude may never think to use the Skill for a release request. If it is bloated, every capability-discovery step carries unnecessary text. If the main body contains every detail, one activation loads too much. If no instruction points Claude to a reference file, that file may never be read. And if a deterministic check remains prose when it could be a script, the model has to reconstruct the same decision each time.

The next article examines which parts of this folder are defined by the open Agent Skills format and which behaviors are specific to Claude Code.

References

• Claude Code: Extend Claude with Skills
• Anthropic Platform: Agent Skills
• Agent Skills: Specification