How to turn a repetitive task into a reusable skill for your AI coding agent

If you keep pasting the same checklist into your AI coding agent — "write a conventional commit, then run the tests, then update the changelog" — you're doing work the agent could remember for you. Most modern agents let you package a recurring procedure into a small, reusable file. In Claude Code these are called skills; the same file also powers slash commands like /deploy. This guide walks through building one from scratch, then explains the principles that carry over to other tools.

What a skill is

A skill is a folder with a single SKILL.md file inside. That file has two parts: YAML frontmatter that tells the agent when to use the skill, and a markdown body with the instructions it follows when the skill runs. The key advantage over stuffing everything into a CLAUDE.md (or AGENTS.md) file is progressive disclosure: the body only loads when the skill is actually invoked, so long reference material costs almost nothing until you need it.

You invoke a skill two ways: directly, by typing /skill-name, or automatically — the agent reads your request, matches it against the skill's description, and loads it if it's relevant.

Where skills live

Where you put the folder decides who can use it. In Claude Code, per the official docs:

• ~/.claude/skills/<name>/SKILL.md — personal, available across all your projects.
• .claude/skills/<name>/SKILL.md — project, committed to the repo so everyone on the team gets the same command.

The folder name becomes the command. A folder called summarize-changes gives you /summarize-changes.

A concrete example

Let's build a skill that summarizes your uncommitted changes and flags anything risky before you commit. Create the directory:

mkdir -p ~/.claude/skills/summarize-changes

Then save this as ~/.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 such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

Two things make this work. First, the description is written for the agent, not for you — it names the triggers ("what changed," "wants a commit message," "review their diff") so the agent knows when to reach for it. Second, the !`git diff HEAD` line is dynamic context injection: Claude Code runs that command and pastes its output into the prompt before the agent reads the skill. The instructions arrive with your actual diff already inlined, so the answer is grounded in your real working tree instead of guesswork.

Make a small edit to any file, start your agent, and try it both ways — ask "what did I change?" to trigger it automatically, or type /summarize-changes to run it directly.

Passing arguments

Skills can take input. A $ARGUMENTS placeholder in the body is replaced by whatever you type after the command, and indexed variants ($0, $1) grab specific words. A skill invoked as /fix-issue 4821 can reference the issue number directly, so one file handles every issue instead of one per ticket.

Five principles for skills that hold up

These apply whether you're writing a Claude Code skill, a Cursor command, or — as of OpenAI's June 2026 Record & Replay feature — editing an automation the agent recorded for you:

1. Write the description for the model. Front-load concrete trigger phrases. A vague description means the agent never auto-loads the skill, and you're back to typing / and remembering names.
2. Keep each skill to one job. A skill that deploys and runs migrations and posts to Slack is hard to trust and harder to debug. Small, single-purpose skills compose better.
3. Inject live context instead of describing it. Pulling in a real diff, a test result, or a file listing beats telling the agent "check the current state" — it removes a step where the agent can guess wrong.
4. Gate anything with side effects. For skills that deploy, migrate, or delete, require explicit invocation rather than letting the agent fire them automatically. You want a human in the loop before irreversible actions.
5. Commit team skills to the repo. Putting project skills in .claude/skills/ and checking them in means every developer — and every agent run in CI — follows the same procedure. Your conventions stop living in one person's head.

When to reach for a skill

The rule of thumb: the moment you paste the same multi-step instructions a third time, or a section of your CLAUDE.md turns from a fact into a procedure, move it into a skill. You get a reusable command, your context file stays lean, and the instructions only load when they're actually needed — which keeps both you and the agent focused on the task in front of you.