You're copying the same prompt context into every agent. Skills stop that.
Every agent your team builds needs the same thing: company voice, brand rules, product glossary, compliance constraints. You've been pasting those blocks into every prompt by hand. They drift. They age. They diverge across agents.
A skill is a reusable bundle: a name, a description, an instruction block, and optionally helper files. Claude loads it on demand. One skill, every agent you own gets the behavior for free.
This module is 90 minutes of building, shipping, and maintaining your first team skill. By the end:
- One shipped skill your team can install.
- A pattern for deciding what belongs in a skill vs. an agent vs. a prompt.
- A governance model so skills don't become the next mega-prompt.
Thinker.
Skills are reusable instructions with a loading contract. Three properties:
- Named. Every skill has a single, unambiguous name. "company-voice", "pricing-policy".
- Described. A one-line description tells the agent when to use it.
- Lazy. Skills aren't loaded unless the task needs them. Saves context.
Skill vs. prompt vs. agent
- Prompt: instructions for one call.
- Agent: a persistent identity with prompts and tools.
- Skill: a reusable bundle shared across agents and calls.
A good rule: if two agents need the same instructions, make it a skill.
What makes a good skill
- Stable (changes quarterly, not weekly).
- Well-scoped (one concept, not a grab-bag).
- Portable (doesn't assume a specific agent's identity).
Talker.
Skills are markdown files with YAML frontmatter. The frontmatter names it. The body teaches the agent.
The skill template
---
name: company-voice
description: Apply the company's writing voice to any drafted
text. Use when drafting customer-facing content, marketing
copy, or documentation.
---
# Company voice
Apply these rules to any drafted text:
## Cadence
- Sentences average 14 words.
- Two short, one long. Declarative openers.
## Vocabulary
- Use: "shipped", "specifically", "the rule"
- Avoid: "leverage", "exciting", "journey", "-ly" adverbs
## Negative space
- No hedging ("I think maybe").
- No corporate filler.
- No feelings words.
## Register
- 4/10 formal. Like talking to a smart colleague.The description is the trigger. The model reads it and decides whether to load the skill. Make it specific and action-oriented.
Helper files
A skill can include referenced files: examples, templates, glossaries. Each file has a name and is loaded when the body references it.
skills/
company-voice/
SKILL.md (the main instructions)
examples.md (5 pieces that exemplify the voice)
glossary.md (product terms, competitor terms)Rememberer.
Skills live in a repo. One folder per skill. Shared across your team.
[company-repo]/skills/
company-voice/
SKILL.md
pricing-policy/
SKILL.md
customer-support-guidelines/
SKILL.md
escalation-matrix.mdOwnership
Every skill has a named owner. Their job: keep it current, review PRs, handle breakage reports. Without an owner, skills rot.
Versioning
Skills live in git. Every change is a commit. If a skill change breaks an agent, you git revert. Same discipline as prompts, same discipline as code.
Installing skills
Claude clients (Desktop, Code, SDK apps) point at a skill folder. On task, the client decides which skills to load based on descriptions. No manual loading per call.
Doer.
Twelve minutes. Ship one skill your team will actually use.
Step 1. Pick the skill (2 min)
Pick something at least three agents in your org already need. Candidates: company voice, support reply template, escalation rules, product glossary. Resist building a speculative one.
Step 2. Draft SKILL.md (4 min)
Use the template from Talker. Write the description carefully, it's the load trigger. Keep the body under 400 words.
Step 3. Test it (3 min)
Point a Claude client at your skill folder. Give the agent a task that should trigger the skill. Check: did it load? Did it apply? You'll see it in the trace.
Step 4. Commit (1 min)
cd [your-skills-repo]
git add skills/my-skill/
git commit -m "skills/my-skill: v1, [one-line purpose]"Step 5. Announce (2 min)
Post in your team channel: "New skill available: my-skill. Triggers when [description]. Replaces [the prompt block you used to copy-paste]. Try it, report breakage."
A committed skill. Two teammates trying it this week. A cleaner baseline for every agent that touches the scope.
- Skill never loads: description is too vague. Name the trigger conditions explicitly.
- Skill loads when it shouldn't: description is too broad. Narrow it.
- Skill contradicts an agent's system prompt: resolve at the skill level (this is about reusability) or at the agent level (agent overrides skill). Pick one rule, apply consistently.
Rookie.
Failure 1. The catch-all skill
You write one skill called "company-context" that includes voice, pricing, legal, and support. The agent loads 2000 tokens to answer a 200-token question.
Fix: one skill, one concept. Split catch-alls into narrower skills with distinct descriptions.
Failure 2. No owner
You ship the skill. Two quarters later the pricing in the skill is out of date. Agents quote wrong prices to customers. No one caught it because no one owned it.
Fix: every skill has a named owner in its frontmatter. Quarterly review on their calendar.
Failure 3. Re-inventing the agent
Your skill becomes 2000 words long. It has a voice, a persona, tool-use rules. You've made an agent, not a skill.
Fix: skills are instructions, not identity. If the "skill" has an identity, it's an agent. Promote it.
Manager.
Skills scale teams of agents. They also rot without process.
Skill standards
Your team writes down skill standards. One markdown page. Covers: how to name a skill, what a good description looks like, how long the body should be, how to handle helper files.
Skill review
Every PR that adds or changes a skill gets reviewed by the named owner. Same as a code review. If the PR has no named owner in frontmatter, reject it and ask for one.
Skill discovery
Your team needs to know what skills exist. A one-page SKILLS.md in the repo lists every skill with name, description, owner. Updated automatically from frontmatter via a script.
Chief.
Risk 1. Skills as policy
A skill is instructions Claude follows across every agent in your org. That makes skills quasi-policy. Changes to pricing-policy change pricing behavior everywhere.
Governance: treat skills as policy documents. Changes go through review at the level appropriate to their reach.
Risk 2. Skill sprawl
Six months in, your team has 40 skills. Nobody knows which are current. Cost goes up because the model loads the wrong ones.
Governance: annual skill audit. Retire skills nobody uses. Merge overlapping skills. A directory of 15 healthy skills beats 40 stale ones.
Risk 3. Skill leakage
A skill with internal pricing or legal content is accessible to every agent, including public-facing ones. If your public agent loads internal-pricing-matrix, you just leaked it.
Governance: skill-level access control. Skills tagged internal load only on internal agents. Audit the load paths.
Founder.
Solo founder: you need maybe 5 skills, ever. Resist the urge to build more.
The solo skill library
- my-voice: voice.md from Module 013, turned into a skill.
- my-context: who you are, what you do, what agents need to know.
- my-apis: your own frequent APIs, with keys in env.
- my-writing-templates: common templates (launch post, update, memo).
- my-escape-hatches: how you want agents to handle weird inputs.
Five skills, covering 95% of your context-sharing needs. New skill every 3-6 months at most.
The quarterly review
Once a quarter, open each skill. Has it drifted from your current practice? Still accurate? 10 minutes per skill. Catches rot early.
Skills are the DRY principle for prompts.
Don't Repeat Yourself, a 60-year-old software idea, applied to agent context. If you're pasting the same context into three agents, it's a skill. Build it once. Own it. Retire it when it stops being true.