Stop pasting the same instructions ten times: write your agent a SKILL.md skill pack
If you have pasted the same instructions into chat for the third time, stop pasting. A SKILL.md skill pack turns a repeated procedure into a manual the agent loads on demand — with a real deploy-flow example, frontmatter rules, scripts, and the six ways skills break.

Let me draw the boundary of this guide first, so you do not waste your time. The site already has a few adjacent articles: "AI Agent Memory" is about how an agent remembers things across sessions, "Agent Handover Pack" is about how a project passes to the next person when someone leaves, and "Agent Permission Contract" is about what an agent may and may not touch. This guide is none of those. It covers exactly one thing: when you have pasted the same set of instructions for the third time, write it down as a skill pack so the agent can pull it out on its own when it needs it. Memory is "remembering", handover is "handing over", permissions are "drawing lines", and a skill is "writing a repeated job down as an operations manual". Four different jobs.
The "Little Bookshelf" used below is a fictional practice project: a small personal book-collection app built with AI help, with a frontend, a backend, and a database. Every step and conversation built around it is invented to explain the method; it is not a record of a real project. Every rule, field name, and version number about skills comes from the Claude Code official documentation, cited at the end.
Are you pasting the same paragraph over and over?
Check the symptoms first. If you write code with Claude Code or a similar agent, you have probably seen this scene: every time you ship a release, you retype "run the tests first, stop if any fail; check the version number went up before building; after deploying to staging, open the homepage and click through login and checkout; if anything breaks, roll back first, do not fix it on staging". You pasted it once, twice, and by the fifth time you start wondering whether you are writing code or working as a repeater.
Worse, when you do not paste it, the agent improvises. Some agents ship without running tests. Some run the tests, watch them fail, and carry on anyway. Some edit production directly. None of this means the model is "dumb". It means the rules you have to teach fresh every time have no fixed home. Rules that live only in your chat history disappear when the session ends, and they never reach the next person at all.
Two common fixes both have flaws. The first is stuffing the rules into CLAUDE.md. That file is read at the start of every session, so one or two lines are fine, but once you pile in the deploy flow, the review checklist, and the launch checks, it keeps growing. The official docs themselves warn: when CLAUDE.md gets too long, split the procedural parts out. The second fix is writing a fresh prompt every time, long and detailed — but you have to rewrite it next time, two people write two different versions, and the same process gets done one way today and another way tomorrow.
A skill pack is built for exactly this case. It is an operations manual that lives in the repository, costs almost no context while idle, and loads itself when the agent judges "this is the moment to use it". You write it once; after that, every time the job comes up, the agent fetches it and follows it. More importantly, it goes into version control: everyone on the team uses the same process, and changing the process means editing a file, opening a PR, and getting a review — not editing a sentence in somebody's chat history.
What a skill pack actually is
In one sentence: a skill pack is a folder containing a SKILL.md file, plus optional scripts and reference files. The folder name becomes the command you type. A folder named deploy-staging gives you /deploy-staging; if the frontmatter sets name: deploy, the command becomes /deploy. The folder can live in three places: your personal ~/.claude/skills/, which works across all your projects; the project's .claude/skills/, which works only for that project; or inside a plugin you share with others.
SKILL.md itself has two parts. The top part is YAML frontmatter between two --- lines, telling the agent "what this skill does and when to use it". The most important field is description: one or two sentences of purpose and trigger conditions, which the agent uses to decide whether to load the skill. The bottom part is Markdown body text: the steps the agent actually follows — what to do first, what to do next, when to stop and ask you, and what counts as done.
The official docs carry a minimal example worth copying: a skill called summarize-changes, whose description reads "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff." The body first pulls the live diff in with a line reading !`git diff HEAD`, then gives two instructions: summarize the changes in two or three bullet points, then list any risks you notice, such as missing error handling, hardcoded values, or tests that need updating; if the diff is empty, say there are no uncommitted changes. The example is small but complete: trigger conditions in the description, live data through dynamic injection, and the body only carries judgment and steps — no filler.
The key idea to grasp is "load on demand". Everything in CLAUDE.md is read in every session, needed or not; a skill's body loads only when the agent decides to use it. So you can put long reference material and detailed checklists inside a skill and pay almost nothing in tokens until the moment it is needed. The official rule of thumb is also the decision rule: when you catch yourself pasting the same instructions again, or when a section of CLAUDE.md has grown from a fact into a procedure, split it into a skill. Facts stay in CLAUDE.md; procedures become skills.
One more thing to know: skill packs follow the Agent Skills open standard, so they work beyond Claude Code. But Claude Code adds its own extensions on top of the standard — invocation control, subagent execution, dynamic context injection. Those extensions may not work in other tools, so keep it in mind when writing: stick to the standard fields and the skill travels anywhere; use the extension fields and it works more smoothly inside Claude Code.
When to write a skill, and when not to
Not every repetition deserves a skill. Ask three questions first.
First: how many times have you pasted this? Something that came up once belongs in the conversation. Something that comes up two or three times in one project, and will come up again, deserves a project skill. Something you paste across several projects belongs in your personal skills at ~/.claude/skills/, available everywhere. The test is not "how important is this" but "how many more times will it appear".
Second: is it a fact or a procedure? A fact is one sentence, like "this project uses pnpm, not npm" — that belongs in CLAUDE.md. A procedure has order, branches, and checkpoints: "run the tests before shipping, stop on failure; bump the version after the tests pass; deploy to staging; open the homepage and click through login" — that is a skill's job. Procedures stuffed into CLAUDE.md make it unreadable; facts written as skills force the agent to load a whole manual for a single sentence.
Third: does it need hands, or only knowledge? Skills can carry scripts, read files, and run commands — they fit "follow these steps" work. If you need the agent to call a live external service or operate a system it cannot otherwise reach, that is not a skill's job; it is an MCP server's job. A skill is the instruction manual you hand the agent; MCP is the lever that lets it actually operate things. The two often work together: the skill says "when to call which tool and how to judge the result", and MCP puts the tool in the agent's hand. The companion guide on this site, "Plug your own project in: build your first MCP server from scratch", covers the second half — read the two together for the full picture.
There is one more case where a skill is not worth it: the procedure itself changes every day. A deploy flow you settled today may change tomorrow. Before a procedure settles, try it a few times in conversation; once the steps are stable and you can recite them in one breath, then write them down as a skill. Freezing something you have not thought through only ends one way: the skill and reality drift apart, the agent follows the stale manual into a mistake, and you spend your time fixing the manual.
The diagram above turns this judgment into a flowchart: count how many times it has appeared, check whether it is a fact or a procedure, then check whether it needs hands. The four exits map to the conversation, CLAUDE.md, a skill pack, and an MCP server — and most everyday repetition lands in the skill pack box.
Write your first skill from scratch: a deploy flow
Enough theory — let us build one. Using the "Little Bookshelf" deploy flow as the example, the goal is a /deploy-staging skill: you say "ship it to staging", and the agent walks through test, version bump, deploy, and verify in fixed order.
Step one, create the folder. Project skills live under .claude/skills/ in the repository, and the folder name is the command name:
mkdir -p .claude/skills/deploy-staging
Step two, write SKILL.md. Start with the frontmatter. The description is the most important line — it decides when the agent remembers this skill on its own. A clumsy but reliable way to write it: use two parts, "what it does + when to use it", and never write a bare noun. A bad example: "Staging deploy skill." That says nothing, and the agent cannot tell when to use it. A good example: "Deploys the current changes to the staging environment and verifies the homepage works. Use when the user says ship to staging, put it on staging, or deploy to staging." The more concrete the trigger words, the better the match — but do not write trigger words only you would use. If a teammate says "deploy it to the test environment", the skill should still match.
The body is written in order: what to do first, what to do next, and when to stop. The version written for "Little Bookshelf" looks roughly like this:
---
name: deploy-staging
description: Deploys the current changes to the staging environment and verifies the homepage works. Use when the user says ship to staging, put it on staging, or deploy to staging.
---
## Steps
1. Run `npm test`. If any test fails, stop and report the failure to the user. Do not continue.
2. Check whether the version in `package.json` is higher than the previous release. If it was not bumped, tell the user to bump it first.
3. Run `npm run build`. A failed build stops the flow the same way.
4. Deploy the build output to the staging environment.
5. After deploying, open the staging homepage, click through login and viewing the bookshelf, and confirm the page loads normally.
## Notes
- Staging data is fake data. Do not perform real operations on it.
- If any step fails, do not work around it yourself. Stop and ask the user first.
Two deliberate choices are baked into that body. First, "stop on failure" appears twice, spelled out as "do not work around it yourself". An agent's default instinct is to get the job done, so if you do not write the stop, it will improvise a way around the failure and hand you a result that "looks successful". Second, the last step asks for a real click-through of the page instead of trusting the deploy command's exit code. A successful deploy command only proves the files were uploaded; it does not prove the page opens. That step is the easiest to skip and the most valuable one in the whole skill.
Step three, test the skill. Go back to the project, type /deploy-staging at the Claude Code prompt, and watch whether it follows the steps. For the first test, deliberately leave a failing test in place and see whether it really stops; then deliberately skip the version bump and see whether it reminds you. A skill only counts as working after this kind of "sabotage test". The official docs offer a more systematic option too: run /doctor for a setup check, or /doctor prompt-audit to review your CLAUDE.md and skill files for outdated or conflicting instructions.
Writing one skill from scratch to working should not take more than half an hour. If two hours pass and it still does not run, the problem is usually not that you wrote too little — it is that the procedure itself is not clear yet, or it was never a good fit for a skill. Go back to the conversation, try it a few more times, and return once the flow is stable.
Give the skill hands of its own: scripts and dynamic context
Steps alone make only half a skill. The truly annoying part of many procedures is not "which step comes when" but "checking a pile of current state before you start". Reviewing a PR means first seeing which files changed, how many lines, and whether any sensitive configuration was touched. Letting the agent look all that up itself is slow and lossy; handing it the state up front lets it get straight to work. That is dynamic context injection: write a line like !`command` in SKILL.md, and when the agent loads the skill it runs the command first and pastes the output into the skill content before starting. The !`git diff HEAD` line in the summarize-changes example works exactly this way.
One rule to remember about dynamic injection: it runs once, when the skill loads, and what it returns is a snapshot of that moment. If a long procedure runs on and the state changes halfway through, the skill does not refresh itself. Do not expect it to work as a monitor — it only prepares "the things you need to look at before starting".
One step beyond dynamic injection is giving the skill scripts of its own. Besides SKILL.md, a skill folder can hold a scripts/ or references/ directory. Say "Little Bookshelf" needs a skill that checks database migrations: the body says "run scripts/check-migration.sh — the script reports whether the migration files match the database", and the script ships inside the skill folder. The agent runs it from the path you gave instead of writing a fresh command each time. The official docs also mention the ${CLAUDE_SKILL_DIR} variable: inside the skill body and inside allowed-tools Bash rules it is replaced with the skill folder's real path, so script paths in a skill never need a hardcoded absolute path — they work on another machine and for another person.
Scripts and dynamic commands both touch permissions, and there is an easy trap here: the allowed-tools declared in a skill are "pre-approvals" — while the agent runs this skill, certain commands do not pop up a confirmation dialog every time. But pre-approval goes through the normal permission flow; it does not bypass permissions. If your organization enforces a setting like allowManagedPermissionRulesOnly, the pre-approval in a skill may simply not apply, and the agent will ask at every step anyway. Do not treat "no confirmation" as the default. For destructive operations — deleting data, calling external services, touching production — let it ask one more time.
Two more frontmatter fields are worth knowing, but do not overuse them. disable-model-invocation: true means "only a human may call this skill; the agent may not load it on its own". It fits skills where an accidental trigger would be expensive, such as wiping a database, clearing a cache, or shipping a public release. context: fork means "run this skill inside an isolated subagent", which cannot see your conversation history, so the skill content must stand on its own. It fits long tasks with lots of intermediate output that you do not want polluting the main conversation — for example, "go through the whole repository's docs and list the outdated parts". Leave both fields out by default: "you and the agent can both call it, running in the current conversation" is enough for most skills.
Where skills live, and who can use them
Location decides scope. Personal skills live in ~/.claude/skills/ and work in every project under your name — for "things I want done this way no matter the project", like your commit message format or your code review checklist. Project skills live in the repository's .claude/skills/ and travel with the code, so every teammate gets them on checkout — for "things this project must do this way", like the deploy flow or the launch checklist. Skills inside a plugin are the distribution form, for "things many people should install and use", like an open-source project's contributor manual.
The wider the scope, the more restraint it needs. Too many broad personal skills force the agent to choose among a pile of them every time, and the chance of picking the wrong one goes up. The same goes for project skills: three to five well-used ones per project is plenty; a dozen piled together cost more to maintain than they return. A simple signal that you have too many: open the /skills menu and you cannot explain what each skill does yourself — time to merge or delete a few.
For teams, project skills carry an organizational benefit: changing a process becomes changing code. Before, when the process changed, you posted in the group chat "from now on run the tests before packaging" and someone always missed it. Now a process change is an edit to SKILL.md, a PR, and a review, and after it lands everyone uses the new version. A new hire checks out the repository on day one and can already see "how this project does things", without learning it by word of mouth. The official docs' /verify skill is a good example: it records "how to verify a change before committing" as a skill, and since Claude Code v2.1.286 the tool even runs it automatically before each commit — provided the skill sits in a qualifying location and you have not switched off the related Git instructions.
Finally, sync and visibility. Skill files are ordinary files that travel with the repository, so syncing is a Git problem. But remember: once a skill is in the repository, its description and body are team consensus. Treat edits like edits to a process — think through the impact before changing, and write in the PR what changed and why. One person quietly rewriting a skill body means the whole team's agents follow the new process the next day, and when something breaks nobody knows who changed it. That is the same level of care as editing a CI configuration.
Skills break too: six common problems
Writing a skill is not the end of the story. The six problems below are mostly covered in the official docs' troubleshooting section; running through them saves a lot of "why is it not doing what I wrote" confusion.
First, a description written like a title. "Deploy skill", "Review helper", "Code check" — the agent cannot match on any of these. Write "what it does + when to use it", in the words a user would actually say. After writing it, read it back: if a new teammate reading only that sentence cannot tell when to use the skill, it fails.
Second, name collisions. Two skills with the same name, or a skill name that collides with a built-in command — which one runs depends on where it came from. Personal, project, and plugin skills each have their own precedence; the naming section of the official docs has the exact rules. When naming a skill, be specific: deploy-staging beats deploy, review-pr beats review. Specific names collide less and match more reliably.
Third, frontmatter that is not on the first line. The official docs are explicit: the opening --- only counts as frontmatter when it is the very first line of the file. One blank line or a comment above it turns the whole frontmatter block into body text and kills the description. When a skill suddenly "stops triggering", check the top of the file first.
Fourth, broken YAML. A missing space or an extra colon in the frontmatter means the parse fails — but the skill still loads, with all fields treated as unset. The symptom: /deploy-staging still types fine, but the agent never invokes it on its own. The official diagnosis is to run with --debug, or run claude plugin validate on the skills directory to find the file whose frontmatter fails to parse.
Fifth, angle-bracket placeholders in the description. Writing "review <branch>" renders escaped in the interface. The official advice is to use square brackets for placeholders, or move the hint into the argument-hint field. A small blemish, but it makes the skill look broken in the menu.
Sixth, a skill written too long. Longer body text is not better. The right length for a skill body is "an experienced colleague can do the job correctly by following it" — not "explain all the background knowledge". Background material belongs in a references/ folder that the body points to when needed, not crammed into the body itself. Once the body gets long, the agent loses the thread and starts improvising.
Start with one skill
If you have never written a skill, do not plan ten at once. Pick one procedure you have already pasted twice this week and walk this checklist:
One, find the paragraph. Open your recent chat history, find the instructions you keep re-pasting, and copy them out. Two, decide where it lives. If it only appears in this project, make it a project skill; if several projects use it, make it a personal skill. Three, write the description. Two sentences, "what it does + when to use it", with trigger words you and your teammates actually say. Four, write the body. Steps in order, what to do when a step fails, and "stop and ask me" on the critical operations. Five, sabotage-test it. Leave a failure in place on purpose, skip a step on purpose, and check whether it stops and warns you. Six, commit it to the repository, so the skill travels with the code instead of sitting on your machine alone.
Once that one skill works, the change is immediate: next time the job comes up, you no longer dig through chat history for the paragraph — one sentence, and the agent fetches the manual and follows it. What you save is not typing time; it is the attention spent re-explaining the rules every time. And attention is the most expensive thing you spend when you write code with an agent.
One last reminder: skills solve "repeated procedures", not "vague ideas". If you cannot yet say how many steps a procedure has or what comes first, a skill cannot help. Get the job clear in conversation first, settle the method, and then write it down as a skill. Reverse the order and the skill only freezes the confusion — more durably, and harder to notice, than a chat log ever could.
Sources: Claude Code official documentation, "Extend Claude with skills" (https://code.claude.com/docs/en/skills.md, read 2026-11-17); Agent Skills open standard (https://agentskills.io, cited in the documentation); for the MCP side, see this site's companion guide "Plug your own project in: build your first MCP server from scratch".
Comments (0)
Sources
Related articles
You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.
Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.
Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.