This started from a simple question — "Isn't a skill just a structured prompt?" — and worked all the way up to wiring several skills together into a multi-step workflow in Claude Code (for example, a stock-analysis pipeline that computes a company's fair value). By the end of this page you'll understand what a skill really is, how it relates to an AI agent, how to write one, where to put it, and how to run it.
A skill is a self-contained package of expertise that an AI model loads only when it's relevant to the task.
In practice it's a folder whose entry point is a SKILL.md file: instructions written in plain language,
optionally accompanied by reference docs, templates, and runnable scripts. Skills follow the open
Agent Skills standard, so the same SKILL.md format works across multiple AI tools, not just Claude Code.
The core idea is simple: instead of pasting the same instructions again and again, you teach the model once and let it
pull that knowledge in on demand.
Understanding the relationship is the fastest way to place skills mentally. An AI agent is the general-purpose actor: a model that can reason, use tools, run code, and act across an environment (Claude Code is one such agent). A skill is not an agent — it's the domain expertise you hand to an agent so it performs a specific job well. Anthropic's own analogy is apt: building a skill is like writing an onboarding guide for a new hire. The new hire (the agent) is already capable; the guide (the skill) tells them how your particular task is done. So the relationship is one of composition: a single agent can pick up many skills, and the same skill can be used by many different agents. Skills turn a general-purpose agent into a specialist only when needed, then get out of the way. This is also why they pair naturally with other agent building blocks like tools/MCP (external capabilities) and subagents (isolated execution) — the skill supplies the "how," the agent supplies the "do."
The idea that "a skill = a structured prompt" is only half right. The core is indeed a structured set of instructions — that part is true. But a skill goes beyond that in two decisive ways. First, a skill is a folder that can bundle reference documents, templates, and executable scripts (e.g. Python) alongside the instructions. Second, while an ordinary prompt is always sitting in the context window, a skill is loaded selectively, only when needed. Those two properties turn it from "just a prompt" into a self-contained, on-demand package of domain expertise.
This is the heart of how skills work. At first, the agent sees only each skill's name and description.
When it judges that a skill is relevant to the task, only then does it read the full SKILL.md body, and if that body
references other files or scripts, it opens those too. The contents of unrelated skills consume no context at all.
That's why you can have dozens of skills available while only the ones relevant to the current task actually occupy context —
a fundamentally different scalability profile from handing over one giant prompt.
A Claude Code skill puts YAML frontmatter (a settings block fenced by ---) before the Markdown body.
All fields are optional, but description — which the agent uses to decide when to apply the skill — is
effectively required. Think of it not as human-facing documentation but as the search keywords that let the agent
discover the skill.
---
name: equity-valuation-workflow
description: A workflow that computes a company's fair value and implied share price.
Runs DCF, enterprise-value analysis, and long-term strategy analysis in order.
Use it when asked whether a stock is fairly valued or what its fair value is.
---
This skill runs a five-stage analysis in order.
Each stage must confirm the previous stage's output exists before proceeding.
1. Run company-research, producing outputs/research.md
2. Verify research.md. If missing, stop and report.
(and so on)A large task like computing a stock's fair value shouldn't be one giant skill; the standard approach is to split it into five independent skills that work together: company research → financial modeling → valuation (DCF) → chart generation → report assembly. What matters is the dependency chain: valuation can't run without the financial model's output, and the model can't place numbers without the assumptions from company research. So each skill is designed to "confirm the previous stage's output exists before proceeding."
Skills can't hand data to each other directly. The actual mechanism of cooperation is passing files through a shared directory (e.g. outputs/). Each skill reads the file the previous stage wrote and writes its own result to a file. That's why every SKILL.md must state its "input: which file to read" and "output: what filename to save." This input/output contract is the plumbing that connects the five skills. You then place a single parent skill (the orchestrator) that binds the five together, with the call order written in its body as a script.
Claude Code stores skills in fixed locations. Personal skills go in ~/.claude/skills/ (usable across all your projects);
project skills go in .claude/skills/ (scoped to that project, and committable to the repo for sharing).
The directory name becomes the command name. Keep both the parent and child skills flat rather than nested,
because each skill needs to be independently discoverable and invocable. What creates the parent-child relationship is not the
folder location but the wording in the parent SKILL.md body.
.claude/skills/
├── equity-valuation-workflow/ → /equity-valuation-workflow (parent / script)
│ └── SKILL.md
├── company-research/ → /company-research
│ └── SKILL.md
├── financial-model/
│ ├── SKILL.md
│ └── scripts/build_model.py
├── dcf-valuation/
│ ├── SKILL.md
│ └── scripts/dcf.py
├── chart-generation/
│ └── SKILL.md
└── report-assembly/
├── SKILL.md
└── templates/report_template.docxYou don't need to specify a path (the folder location) at run time. There are two ways.
(A) Ask in natural language: if the description matches, the agent selects the parent skill automatically.
(B) Name it with a slash command: / + skill name starts it deterministically. You can pass arguments too.
# (A) Natural language — let the agent choose
Analyze Apple's fair value and give me the implied share price.
# (B) Slash command — start it deterministically (with an argument)
/equity-valuation-workflow AppleWriting "run X" in the parent body is an instruction, not a guarantee of automatic execution. Two frontmatter fields make it
more robust. Adding context: fork runs that skill in an isolated subagent, letting you execute heavy analysis stages safely.
Adding disable-model-invocation: true stops the agent from triggering it on its own and limits it to manual
/name invocation — useful when you don't want a process with real financial consequences firing unintentionally.
Official documentation and specifications worth bookmarking:
A skill is "a structured prompt + bundled resources + on-demand loading," and it's best understood as the domain expertise you
hand to a general-purpose agent. A multi-step workflow is realized by combining
a parent skill (the script) + each skill's input/output contract + a shared file location.
Start with the smallest setup — one parent plus one child in .claude/skills/, get it running,
then add stages from there; that's the order that keeps you from getting lost.
One tool worth a dedicated deep dive of its own is the skill-creator plugin, which automates the
evaluate-and-iterate loop — measuring separately whether the agent triggers a skill on the right prompts and whether its output
matches what you expect. We'll cover skill-creator in depth in a follow-up post.