If you keep pasting the same block of instructions into your coding agent — the same review checklist, the same commit-message rules, the same "here's how we deploy" — you're doing by hand what a skill does automatically. A skill is a folder with one required file, SKILL.md, and once it exists the agent loads it when it's relevant or you fire it directly with /skill-name. This is the fastest, most portable upgrade you can make to an agent workflow, and it follows the SKILL.md open standard, so the folder you build here also runs in claude.ai, Cursor, and ChatGPT.
Here's the whole thing, empty folder to working command, in four steps.
Step 1 — Make the folder#
The directory name becomes the command you'll type. Put it in your personal skills folder to use it across every project:
mkdir -p ~/.claude/skills/summarize-changes(Use .claude/skills/summarize-changes inside a repo instead if you want to commit it for your team. Personal → all your projects; project → that repo only.)
Step 2 — Write SKILL.md#
Every skill needs a SKILL.md with two parts: YAML frontmatter between --- markers that tells the agent when to use the skill, and markdown instructions it follows when the skill runs. Save this to ~/.claude/skills/summarize-changes/SKILL.md:
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any
risks you notice — missing error handling, hardcoded values, tests that need
updating. If the diff is empty, say there are no uncommitted changes.Two things are doing the work here:
- The
descriptionis the trigger. The agent reads every skill's description and matches your prompt against it. Write it as when to use this, key use case first — "Use when the user asks what changed…" — not as a title. A vague description is the single most common reason a skill never fires. - Dynamic context injection does the rest. The
!-prefixed line in the example — the one callinggit diff HEAD— runs before the agent sees the skill, and its output replaces the line. So the instructions arrive with your actual working-tree diff already inlined; the agent reasons over real data, not a guess. For multi-line commands, use a fenced block opened with a triple-backtick bang instead of the inline form.
Step 3 — Test it#
Open a git project, make a small edit, and start the agent:
claudeTrigger it two ways. Automatically, by saying something that matches the description:
What did I change?Or directly, by name:
/summarize-changesEither way you should get a short summary of your edit and a list of risks. If it doesn't fire automatically, your description is too vague — add the words you'd actually say.
Step 4 — Two upgrades that make it feel native#
Once the basic skill works, two frontmatter fields turn it from "a saved prompt" into a real tool.
Pre-approve the tools it needs so the agent doesn't stop to ask permission mid-run. A commit skill, for example:
---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---
Stage and commit the current changes with a clear, conventional message.allowed-tools grants those tools only for the turn that invokes the skill — the grant clears on your next message, and it doesn't restrict anything else.
Keep side-effect skills manual. Notice disable-model-invocation: true above: it means the agent can never run this on its own — only you can, by typing /commit. Use it for anything you want to time yourself: deploy, commit, send-email. You don't want the agent deciding to ship because your code "looked ready."
The one rule that keeps skills fast#
Keep the SKILL.md body under 500 lines. Once invoked, a skill's content stays in context for the rest of the session, so every line is a recurring token cost. State what to do, not why. When you need long reference material — an API spec, a big example set — put it in a separate file in the skill folder and link it from SKILL.md so it loads only when the agent actually needs it:
summarize-changes/
├── SKILL.md # required — the instructions
├── reference.md # loaded only when linked and needed
└── scripts/
└── check.sh # executed, not loaded into contextThat's the whole model: a folder, a SKILL.md, a good description. Everything else — arguments, forked subagents, bundled scripts — is an extension of these four steps.
Deciding whether a given feature should even be a skill, versus a running service? That's a different call, and we made it a one-pager: Agent Skill or MCP server? For the broader mid-July shifts that made skills portable in the first place, see the Founder's Wire.
