How to Write Your First Agent Skill

You have house rules for your coding agent: how commit messages should look, what a code review should check, how meeting notes should be structured. So you paste them into the chat at the start of every session — and by message ten the agent has drifted anyway. Next session, you paste again.

The problem is not memory. The instructions live in your clipboard instead of in a file the agent loads every time. A skill is that file.

What a skill is

A skill is a folder containing one file: SKILL.md. It has two parts.

The YAML frontmatter carries two fields — a name and a description. The description is the trigger: the agent scans the descriptions of its skills to decide which ones apply to your request. So the description does two jobs — say what the skill does, and name the situations where it fires. Write it as "does X. Use when the user asks for Y."

The body is plain markdown: the workflow, the rules, an example. No code, no config beyond the frontmatter.

Teardown: a commit-message skill

The smallest skill in my pack generates commit messages, and it shows every part doing a job. Its frontmatter, verbatim:

---
name: git-commit-message
description: "Generates conventional-commit messages from staged changes: type prefix + English imperative subject (≤50 chars) + optional body explaining why. Use when the user asks to write, generate, or polish a git commit message."
---

The workflow is five numbered steps, in execution order:

1. Look at the changes (git status --short, git diff --cached --stat). If nothing is staged, stop and ask — never invent a message out of nothing.
2. Pick exactly one type prefix: feat, fix, docs, refactor, test, chore. A change that mixes types gets split into two commits, not averaged into one.
3. Write the subject: type + imperative phrase, ≤50 characters. Empty subjects like "update code" are banned.
4. Write an optional body: 1–3 lines explaining why, not a play-by-play of how.
5. Output a ready-to-run git commit command, not bare text the user has to assemble.

Then come the rules that encode judgment — the things you would otherwise keep correcting in review:

• The subject is for skimmers; the body is for future-you in three months. Keep the two jobs separate.
• No meta-commentary in the message ("generated by AI", etc.) — the message is about the change, nothing else.

And one worked example, with the expected output:

git commit -m "feat: add CAPTCHA verification to login endpoint" -m "Blocks automated credential stuffing; CAPTCHA valid 5 minutes, account locks 10 minutes after 3 failures."

Finally, the anti-patterns — the failure modes, named explicitly:

• Writing a message for an empty staging area: no diff, no commit message.
• Catch-all chore: labeling every feat and fix as chore until the type system means nothing.
• Novel-length subjects that praise the change instead of naming it.
• Body as implementation log ("first changed line 20 of a.py, then b.py…") — the diff already shows that; the body explains why.

Each part earns its place. The description decides triggering. The numbered steps fix the order of operations and include a stop condition. The rules hold the judgment calls. The example anchors the output format better than a paragraph of prose. The anti-patterns tell the agent what to refuse.

Writing your own

1. Pick a workflow you have explained at least three times. Repetition is the selection criterion.
2. Write the description first. If you cannot write a clean trigger, the skill's scope is too wide.
3. Write the workflow as numbered steps in execution order, with stop conditions for the cases where it should not proceed.
4. Add the rules you always end up correcting — naming, format, what to do when the input is ambiguous.
5. Add one worked example — real input, expected output, no placeholders.
6. Add the anti-patterns. The ways this workflow goes wrong are as instructive as the steps.
7. Keep it short. Two minutes to read. If a rule never fires, delete it; a short, accurate skill beats a long, stale one.

Using it

Drop the folder into your agent's skills directory, and the agent picks it up by matching the description — no further configuration. If you want working examples first, the five skills in the pack this teardown came from are free and MIT-licensed: commit messages, code review, meeting minutes, technical proofreading, and structured deep research.

Repo: https://github.com/alapha888/agent-skills-en

npx skills add alapha888/agent-skills-en

The structure is the stable part; the rules are yours. Take the workflow you explained three times this week, and write it down once.