Open a new chat with Claude to write this week's client update, and the first thing you do is paste in the same reminder: use our template, keep it under one page, don't promise a date nobody's confirmed. Do that often enough and you start keeping the reminder in a notes app, just to copy it faster next time. The knowledge of how your team actually does this task lives in that pasted paragraph — not in the AI, and not anywhere a teammate could find it either.
Why the pasted paragraph never actually stuck
A long instruction pasted into every conversation costs more than it looks like it does. It eats into the context window — the amount of text a model can hold in one conversation — whether that turn needs it or not. Different people paste slightly different versions, so the 'house style' drifts depending on who's typing. And it doesn't travel: the wording you finally got right in one Claude chat does nothing for the coding agent your engineers use, or for an automated pipeline calling the API. Custom instructions saved inside one tool solved this for that one tool, and stopped exactly there.
What Agent Skills actually change
Agent Skills, an open format Anthropic published in October 2025, are a folder on disk with one required file, SKILL.md, that states what the skill does and when to use it. Claude reads only the folder's name and a one-line description at the start of a conversation — a few dozen tokens — and opens the full file only when a request actually matches that description. That loading pattern is called progressive disclosure: detail arrives in the size the task needs, not all at once. You can have twenty skills installed and pay the token cost of only the one that fired.
The same folder works, unmodified, wherever Claude runs: as a project skill in Claude Code, uploaded as a zip in claude.ai's settings, or attached to an API call so an agent you built can use it. OpenAI, Google and GitHub's tooling have since adopted the same format, so a skill is becoming a portable unit of know-how rather than something locked inside one vendor's chat window.
Build one: a deal-review skill
Take a task that repeats every week and genuinely needs a fixed shape: turning a raw sales call transcript into a one-page deal review. A skill for it needs three things in one folder — instructions, a template to fill in, and a script that checks the draft before anyone reads it.
---
name: deal-review
description: Turn a raw sales call transcript into a one-page deal review using our standard template. Use when the user shares a call transcript, or asks for a deal review or a call summary.
---
# Deal Review
## Quick start
1. Read the transcript the user pasted or attached.
2. Fill in every heading in templates/deal-review-template.md.
If the call didn't cover something, write "Not discussed" —
never guess a number or a date.
3. Run scripts/validate.py on the draft before showing it to the
user. If it reports a missing section, fill it in and re-run.import sys
REQUIRED = [
"## Budget",
"## Decision maker",
"## Timeline",
"## Objections raised",
"## Next step",
]
def main(path):
text = open(path).read()
missing = [h for h in REQUIRED if h not in text]
if missing:
print("Missing sections:", ", ".join(missing))
sys.exit(1)
print("All sections present.")
if __name__ == "__main__":
main(sys.argv[1])Install it, then test it before you trust it
- Claude Code: drop the folder in .claude/skills/deal-review/ at the project root. No upload step — Claude Code reads the filesystem directly.
- claude.ai: zip the same folder and upload it under Settings → Features (needs a Pro, Max, Team or Enterprise plan with code execution turned on).
- API: upload it once through the /v1/skills endpoint and reference its skill_id from any agent call that also uses the code execution tool.
- Then hand it a real transcript and read the draft yourself before you let the validation script be the only check anyone runs.
None of those three uploads talk to each other. A skill you upload to claude.ai isn't visible to the API, and a Claude Code skill is a local file the API and claude.ai can't see at all. If your team works across two of these surfaces, you install the same folder twice — a real limitation to plan around, not a rough edge that smooths out by itself.
Skills teach; they don't connect
Set this against Model Context Protocol, which we've covered before for wiring Claude to a live system such as an orders database. MCP gives Claude access — a tool it can call, data it can read. A skill gives Claude method — instructions for doing a task well once it already has that access. A skill can tell Claude how to write a deal review; it can't go fetch the CRM record itself. Most real workflows end up needing both: an MCP server for the data, a skill for the house style around what to do with it.
The question isn't whether Claude can write a good deal review. It's whether it has to be taught what "good" means every single time it's asked.
Where it's the wrong tool
Skip a skill for anything that won't repeat — a one-off analysis or a single email is faster to just ask for directly than to package up. Skip it too when the task depends on live, changing data rather than a fixed process; that's what MCP or a plain tool call is for, not a folder of instructions. And treat a skill exactly like you'd treat installing software from someone else: Anthropic's own guidance is to only run skills you wrote yourself or got directly from Anthropic, because a skill's instructions can direct Claude to run bash commands and read files — and a malicious one can turn that into data leaving somewhere it shouldn't.
Common mistake
A description like 'helps with documents' either fires on everything or on nothing, because that one line is all Claude matches your request against before deciding whether to open the file. Name the exact task and the exact trigger — as specific as 'turn a sales call transcript into a deal review one-pager, use when the user shares a call transcript or asks for a deal review' — or the skill sits installed and unused.
The pasted paragraph in your notes app is institutional knowledge with no address — it exists only in whoever remembered to bring it to the chat that day. A skill gives that same knowledge a folder, a version, and a place every tool your team uses can go and find it.
Deciding which of your team's repeated workflows are worth turning into a skill — and which ones need real system access instead — is exactly the kind of scoping we do in an AI Opportunity Assessment.