Claude Code Skills Deep Dive (1): From a Markdown File to a Portable Folder

TL;DR: The Agent Skills format defines a portable folder: SKILL.md supplies discovery metadata and core instructions; references hold knowledge to read when needed; scripts perform deterministic operations; and assets provide templates and materials. Claude Code accepts that core, then adds product-specific invocation, execution, permission, and path behavior. Write the portable core first, and be explicit about which behavior depends on Claude Code.

In Part 0, we placed Skills in the capability stack: they participate in selection somewhat like tools, but activation loads operational knowledge rather than entering a separate atomic executor.

Now look at the filesystem. Why is a Skill an entire folder instead of a single deploy.md file?

One Markdown file soon becomes three kinds of material

Start with a release-check Skill containing four steps:

1. Inspect the working tree. 2. Run tests. 3. Check the changelog. 4. Summarize risks. 

As the workflow matures, it needs a detailed versioning policy to consult, a version-number validator to run, and a release-report template to fill in. Putting all three into the same Markdown file would load policy, code, and template alongside the core procedure. It would also blur the distinction between instructions needed every time and material needed only for a particular branch of the work.

The Agent Skills specification therefore defines a Skill as a directory with SKILL.md at its entry point, not merely as a Markdown document:

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

These locations express different roles:

The folder is both a capability manual and a bundle of working materials.

SKILL.md is an entry point, not a warehouse

The entry file does at least three jobs: its metadata says what the Skill is and when to use it; its body explains what to do after activation; and it points Claude toward supporting files at the right moment.

The third job is easy to miss. Merely placing version-policy.md in references/ does not tell Claude why or when to read it. The entry file should supply conditions:

## Supporting resources  - When evaluating a version number, read `references/version-policy.md`. - For a mechanical format check, run `scripts/validate-version.sh`. - For the final report, use `assets/release-report.md`. 

This is navigation, not a redundant directory listing. Progressive disclosure works only if Claude can find the next resource when it becomes relevant. Think of SKILL.md as a map: the description tells Claude when to open it, the body identifies the main route, and supporting files are branches that need not be copied into the map itself. Too little guidance makes the map unusable; too much detail defeats the purpose of loading information in stages.

What the open format standardizes

The open specification requires YAML frontmatter followed by a Markdown body. A minimal portable core looks like this:

--- name: release-check description: Check whether a version is ready to release; use when preparing a release. --- 

Here name gives the folder a stable identity, description says both what it does and when to use it, and the Markdown body stores the instructions. scripts/, references/, and assets/ are optional conventional locations. The specification also defines optional metadata such as license, compatibility, and an extensible metadata map; allowed-tools is experimental.

The format does not standardize Claude Code's UI, subagent types, or session lifecycle. Another agent can understand the same folder's instructions, but each host decides where to discover it, how to show the metadata to the model, how to activate it, where a script runs, and what to do with the result. This is the boundary between a format standard and a product runtime.

What Claude Code adds

Claude Code plugs Skills into its commands, tools, subagents, hooks, and permission system. Its frontmatter can therefore express additional, product-specific behavior. Group those extensions by the question they answer:

A deployment Skill might be user-invoked only; a research Skill might run in a separate subagent context; a frontend Skill might apply only to particular paths. These features are useful, but they are not promises made by every Agent Skills-compatible host. The same file effectively contains two layers:

Portable Agent Skills core name · description · instructions · supporting files ↓ interpreted by a host Claude Code extensions invocation · fork · paths · hooks · permissions · dynamic context 

When authoring a Skill, know which layer a behavior depends on. “Works in Claude Code” should not silently become “guaranteed by the Agent Skills standard.” The Claude Code Skills guide documents its own extensions; the open specification defines the portable baseline.

The apparently contradictory name field

The open specification requires name and expects it to match the parent directory. Claude Code can derive a local Skill's command identity from that directory, so its own documentation allows the frontmatter name to be omitted in some local cases.

These are answers to different questions. The open format asks how a folder preserves a verifiable identity outside the current host. Claude Code asks which /skill-name a user types when the local directory is already known. A personal, Claude Code-only Skill can rely on directory inference. For a Skill intended to travel between clients, explicitly writing a standards-compliant name and description is the safer choice.

The same principle applies to other extensions: write the portable core explicitly, add host-specific controls where useful, and do not make an extension carry the whole meaning of the workflow. For example, “wait for user confirmation before deployment” belongs in the body instructions, not solely in a Claude Code setting that prevents automatic invocation. The setting is an extra safeguard; the instructions preserve the workflow's intent.

A script does not turn a Skill into a tool

Bundling a script does not erase the Skill/tool boundary. A host-registered tool has a defined invocation interface, permission identity, and result protocol. A script inside a Skill is implementation material carried by that Skill. Claude still follows the instructions to decide when to run it through an existing execution capability:

Skill instructions: “Check the version file first.” ↓ Existing execution capability: Bash / code execution ↓ Bundled script: scripts/validate-version.sh 

Scripts suit steps with clear inputs and repeatable outputs. Instructions suit contextual judgment, exceptions, and orchestration. Leaving every deterministic check in natural language asks the model to reinterpret it each time. Hard-coding the entire workflow into one script, however, sacrifices Claude's ability to handle context and exceptions. The Skill folder lets the two approaches work together.

An asset is not a reference

Both references/ and assets/ might contain Markdown, JSON, images, or templates. Their distinction is purpose, not extension: a reference is read to inform Claude's judgment; an asset is used to make the final deliverable. An API specification belongs with references, while a report template belongs with assets.

This distinction helps with review. Changing a reference may change Claude's decisions. Changing an asset mainly changes the output's form. Changing a script may change a deterministic operation. Changing SKILL.md can change discovery and the overall workflow. A folder gives us clearer change boundaries than a single versioned prompt.

Why custom commands converged with Skills

An older custom command could already expose Markdown as /deploy: the user could save a prompt and invoke it repeatedly. Skills add a discoverable description, a folder of supporting files, and richer frontmatter for invocation and execution. Claude Code still supports older command files, but recommends Skills for new work.

This is more than renaming slash commands. It moves from “the user expands a stored prompt” toward “the user or model can discover a capability bundle.” Still, not every built-in command is a Skill: some commands trigger product-internal behavior, while a bundled Skill primarily supplies instructions and orchestrates tools. Sharing a /name entry point does not imply identical execution semantics.

The open standard makes the bundle recognizable; the product runtime makes it participate in a session. Both layers matter, and they should not be confused.

The next article follows metadata, instructions, and resources through their different loading times to examine the context-cost trade-off behind progressive disclosure.

References

• Agent Skills specification
• Anthropic Platform: Agent Skills
• Claude Code: Extend Claude with Skills
• Part 0: From Repeated Prompts to Callable Capabilities