HyperTeamsCapturing 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 | 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.
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
description matters most
The model reads that one line to decide whether to load this skill. Exactly the same principle as MCP tool descriptions.
Always include "when to use it." Without it, it never gets called.
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
<working directory>/.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
graph TD
A["You repeat the same work"] --> B{"Is the instruction<br/>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"| FThree signals that a skill is right:
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 |
| Something that calls an external system | an MCP tool |
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
The principle that scope is best written as what not to do holds here too. It matters more in a skill because several people use it.
Keep the material alongside
One example is more precise than ten lines of explanation.
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:
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