> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # Skills > A skill packages a workflow into a directory of SKILL.md and supporting files that an AI agent loads on demand, so the same procedure runs reproducibly. ## Overview A skill is a reusable unit of workflow knowledge for an AI agent, defined as a directory holding a required `SKILL.md` file and optional supporting files. The `SKILL.md` encodes the procedure: step-by-step guidance, a fixed output format, and the decision points that genuinely need a human. Once written, it is invoked as a command or triggered automatically, and produces similar results no matter who runs it. This page explains the principles behind skills, their structure, and how to create and invoke one. ## Design principles A skill exists to give an agent the context it otherwise lacks for real work: the domain expertise and procedures specific to your organization. Its design rests on four principles. Capture your organization's procedural knowledge in a version-controlled form, so the agent works from supplied context instead of guesswork. Turn multi-step tasks into consistent, auditable procedures that run the same way no matter who invokes them. Write a skill once and use it with any skills-compatible agent or product. Only the `name` and `description` load at startup; the body and supporting files load only when they become relevant. ## Anatomy of a skill A skill lives in its own directory (in Claude Code, `.claude/skills//`) and consists of a `SKILL.md` file plus optional supporting files. ### Directory layout ```text Directory layout theme={null} .claude/skills/ └── commit-message/ ├── SKILL.md # Required. Frontmatter + instructions ├── references/ # Optional. Read only when the body links to them │ └── semantic_versioning.md └── scripts/ # Optional. Executed, not loaded into context └── check_format.sh ``` | Part | Role | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `SKILL.md` | The required file, holding the frontmatter that identifies the skill and the instructions for the agent. | | `references/` | Optional supporting documents — full rule tables, templates, long examples — linked from the body and read only when needed. | | `scripts/` | Optional utility scripts the body tells the agent to run. Only their output enters the context, not their source. | ### Structure of SKILL.md `SKILL.md` has two parts: YAML frontmatter that identifies the skill, and a Markdown body with the instructions and examples. ```md SKILL.md theme={null} --- name: commit-message description: Generate commit messages that follow semantic versioning rules. Use when committing changes or when asked to write a commit message. --- # Instructions 1. Inspect the staged diff and classify the change as major, minor, or patch. 2. Combine it with a type prefix (feat, fix, docs, ...) per references/semantic_versioning.md. 3. Output a single-line message in the form `-: `. ``` | Part | Role | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The identifier, kept matching the directory name — which is also where the invoking command (`/commit-message` in Claude Code) comes from. | | `description` | When the skill applies. The agent matches requests against this text, so it decides whether the skill triggers at all. | | `allowed-tools` | Optional. The tools the skill is allowed to use. An experimental field, so support varies between implementations; see "Keep tool permissions minimal" below for how to scope it. | | Body | The instructions the agent follows once the skill is active: steps, output format, examples. | ### Progressive disclosure A skill is loaded in stages rather than all at once. At session start the agent reads only the frontmatter of every installed skill. The body is read when a request matches the `description`, and files under `references/` are read only when the body points to them. Instructions that would otherwise sit permanently in a system prompt or an MCP tool definition therefore cost almost no context until the moment they are needed. ## Creating a skill ### Name and describe for discovery The `name` and `description` are the only parts loaded before the skill is chosen, so they carry the whole burden of discovery. * Name skills after the action, in lowercase and hyphens. Avoid vague names such as `helper` or `utils`. * Write the `description` in third person, state both what the skill does and when to use it, and include the words a user would actually say. ### Write for a capable reader The agent already has general programming knowledge, so include only what it cannot infer: your conventions, your constraints, your procedures. Concise instructions outperform thorough ones. * Keep the `SKILL.md` body under roughly 500 lines; move bulk material to `references/` files. * Keep references one level deep — every supporting file should be linked directly from `SKILL.md`, because nested reference chains get read partially. * Use one term per concept throughout (always "field", not a mix of "field", "box", and "element"). * Avoid time-sensitive statements ("before August, use the old API") that silently become wrong. * Heavy use of "MUST", "NEVER", and "ALWAYS" is a warning sign. Explaining why a rule exists works better than stacking prohibitions, because the agent can then judge unforeseen situations correctly. * Also state what to do off the happy path — a missing argument, an external service returning an error. When the instructions cover only the normal case, the behavior in exceptional cases varies from run to run. ### Provide a template for the output format When output consistency matters, provide a template for the output format and match its strictness to the task — anywhere from a loose example of the structure to an exact template the agent must always follow. * Where downstream processing or tools depend on the shape of the output — data formats, standardized reports — use a strict template and state that this exact structure must always be used. * Where the structure may reasonably vary with the content, present the template as a sensible default and note that it can be adapted to the situation. ```md A strict template (for report generation) theme={null} ## Report structure ALWAYS use this exact template structure: # [Analysis Title] ## Executive summary [One-paragraph overview of key findings] ## Key findings - Finding 1 with supporting data ## Recommendations 1. Specific actionable recommendation ``` ### Show with input/output examples Elements that resist description — style, tone, level of detail — are best conveyed as input/output pairs. Showing the desired output carries more reliably than describing it. ```md Examples in the body (for commit-message) theme={null} # Examples - Input: fix a typo in the README installation steps Output: `patch-docs: fix typo in installation steps` - Input: add JWT-based login to the auth service Output: `minor-feat: add JWT login to auth service` ``` When the output must always follow the same structure, use the template from the previous section instead of examples. Examples also consume context every time the body loads, so move long or numerous examples into a `references/` file that is read only when needed. ### Match freedom to fragility Decide how much latitude the instructions leave, based on how fragile the task is. Where many approaches are valid — a code review, an analysis — give heuristics and let the agent choose the route. Where the operation is fragile or must be consistent — a migration, a release step — give the exact command and state that it must not be modified. When several tools could work, name one default and mention an alternative only for the cases where the default fails. ### Keep tool permissions minimal Grant a skill only the tools its workflow actually uses. In Claude Code, declare them as `allowed-tools` in the frontmatter of `SKILL.md`: ```yaml theme={null} allowed-tools: Read, Glob, Bash(git status*), Bash(git diff*) ``` * Do not allow tools that never appear in the procedure. A skill that only reads has no need for Write or Edit. * Scope Bash per command: split a broad pattern like `Bash(git *)` into specific ones such as `Bash(git status*)` and `Bash(git diff*)`. * As a rule, do not allow destructive commands such as `rm` or `git push --force`. A skill that only provides knowledge and uses no tools needs no `allowed-tools` declaration at all. ### Build in verification Multi-step skills drift without checkpoints. Two patterns keep them on track: * **Checklists.** Have the skill emit its step list and check items off as it progresses, so skipped steps become visible. * **Feedback loops.** Pair each output with a validation step — a validator script, a lint run, a checklist review — and instruct the agent to fix and re-validate until it passes before moving on. ### Orchestrate sub-agents A skill with many steps runs more reliably as an orchestrator — the `SKILL.md` body directs the flow while independent subtasks are handed off to sub-agents — than as one long procedure executed by a single agent. * Run subtasks with no dependencies between them in parallel; per-dimension reviews or multi-area investigations have no reason to run in sequence. * Make each sub-agent's instructions self-contained. Sub-agents cannot see the calling conversation, so pass all necessary context in the prompt. * Always follow a parallel phase with a step that consolidates the results. * Spell out in the body how data crosses steps — which later step consumes the output of an earlier one. Keep the parallel count to a handful; beyond that, the cost of consolidation outweighs the gain from parallelism. ### Create with skill-creator skill-creator is a tool from Anthropic that supports writing a new skill. In Claude Code, install it from the official marketplace: ```text theme={null} /plugin install skill-creator@claude-plugins-official ``` Describing the skill you want starts an interactive flow. skill-creator confirms the purpose and the decisions the skill should surface, then scaffolds the directory — `SKILL.md`, `references/` files, and `scripts/` when needed — in the structure described earlier on this page, and cleans up files that turn out to be unnecessary. ## Invoking a skill A skill is invoked in two ways. Explicitly, as a command, or automatically, when the agent matches the request against the skill's `description`. Both paths run the same `SKILL.md`; the command is simply the direct handle. A skill is not limited to a single-shot task. Its body can drive a longer, interactive flow that asks clarifying questions, runs sub-agents in parallel, and calls other skills as steps. See [Vibe Coding](/ai/vibe-coding) for the collaboration basics that skills build on, and [Agentic Workflow](/ai/agentic-workflow) for the delegation model where multi-step skills run.