# Capturing procedures as skills > **What you will learn** > How a skill differs from an instruction or an agent, where it lives, and when > to make one. ## Three units of reuse "How to reduce repetition" has now come up three times. They are easy to confuse, so: | Unit | Where it lives | What it holds | |---|---|---| | **Instruction template** | your notes | text you paste each time | | **[Sub-agent](/guide/cn-create-agent)** | a Connect workspace | role, tone, rules | | **Skill** | **a file inside the working directory** | **a procedure and its material** | What makes a skill different is that **it exists as a file.** ## The folder is the state Skills are not stored in a database. **They are discovered by walking folders.** ``` /.claude/skills/ deploy-check/ SKILL.md report-format/ SKILL.md template.md ``` The consequences of that design matter. | Consequence | Meaning | |---|---| | **It is under git** | the team shares it, history exists, you can revert | | **The terminal sees it too** | the same skill whether you direct from the screen or type it | | Copying the folder carries it | easy to move to another project | > **The first is the key one.** An instruction in personal notes belongs to that > person; a skill goes into the repository and becomes **a team asset.** ## One SKILL.md is enough ```markdown --- name: deploy-check description: Runs through the pre-deployment checks in order. Use before a deploy or release. --- # Deployment check ## Order 1. Confirm all tests pass 2. Confirm the build succeeds 3. Summarise the changed files 4. Flag any change that is hard to undo, separately ## What to look at - Are migration files included - Were environment variables added (they need applying at the target) - Were external API calls added ## What not to do - Do not actually deploy. This ends at checking and reporting. ``` ### `description` matters most **The model reads that one line to decide whether to load this skill.** Exactly the same principle as [MCP tool descriptions](/guide/mcp-capabilities). ``` ✗ description: deployment check → no idea when to use it ✓ description: Runs through the pre-deployment checks in order. Use before a deploy or release. → says both what it does and when to use it ``` **Always include "when to use it."** Without it, it never gets called. ![The Skills tab. It separ](/guide-assets/ht-skills.png) The Skills tab. It separates **this folder** from **elsewhere** and states the install path — only this folder is editable. ## Four places Skills are discovered in four places. All four are read; **only one is written.** | Place | Scope | Editing | |---|---|---| | **project** | this working directory only | **only this one** | | user | all your projects | read only | | policy | installed by an administrator | read only | | plugin | brought in by a plugin | read only | Installing or removing from the screen touches **only `/.claude/skills`.** The other three belong to the machine, the administrator, or a plugin's own updater — they are listed, not edited. > **So build skills in the project place.** Then they go into that folder's > repository and the team uses them together. ## When to make one ```mermaid graph TD A["You repeat the same work"] --> B{"Is the instruction
nearly identical each time?"} B -->|"no"| C["Just converse"] B -->|"yes"| D{"Is there attached material?"} D -->|"no"| E["An agent or a template"] D -->|"yes"| F["A skill"] B -->|"yes"| G{"Does the team share it?"} G -->|"yes"| F ``` **Three signals that a skill is right:** ``` □ the instruction has material attached (a form, a checklist, an example) □ the team has to share it □ the content differs per project ``` The third is the most skill-like case. "Deployment check" differs by project, and because the skill lives inside the working directory, **each project keeps its own version.** ## When not to | Situation | Instead | |---|---| | A one-off | just converse | | The instruction varies a lot each time | narrow it in conversation | | A tone or role the whole team uses | a [Connect sub-agent](/guide/cn-create-agent) | | Something that calls an external system | an [MCP tool](/guide/mcp-why-standard) | **A skill is a procedure, not a tool.** If something has to be looked up or executed, that belongs on the tool side. ## Practical tips ### Write what not to do ``` ## What not to do - Do not actually deploy. This ends at checking and reporting. ``` The principle that [scope is best written as what not to do](/guide/ai-intent-context) holds here too. It matters more in a skill because **several people use it.** ### Keep the material alongside ``` report-format/ SKILL.md template.md ← point at this from SKILL.md example-good.md ``` [One example is more precise than ten lines of explanation](/guide/ai-how-to-ask). ### Match the folder name to `name` A frontmatter `name` differing from the folder name still works. But **the folder name is the identity for anything touching the filesystem**, so a mismatch confuses deleting and moving. Keep them the same. ### Keep a review list About once a quarter: ``` □ is there a skill nobody has invoked □ does each description say when to use it □ has a project changed while its skill still holds the old procedure ``` **The third is specific to skills.** When the procedure changed and the skill did not, **it confidently repeats the wrong procedure.** --- ## Check yourself **1. What decisively separates a skill from an instruction template?**
Answer **That it exists as a file inside the working directory.** So it is under git and shared by the team, and the same skill is visible whether you direct from the screen or type in the terminal.
**2. What must a `description` include?**
Answer **When to use it.** The model reads that line to decide whether to call the skill, so "what it does" without "when" means it never gets called.
**3. Which of the four places can you edit, and why only that one?**
Answer **Only project (inside the working directory).** The other three — user, policy, plugin — belong to the machine, the administrator, and plugins, so they are listed but not touched.
--- Now turning documents into usable material → [Turning documents into material](/guide/ht-documents)