How to Write Your First Agent Skill

A developer published a free, MIT-licensed pack of five agent skills, including one that generates conventional-commit messages, and outlined the minimal structure each skill follows: a folder containing a single SKILL.md file with YAML frontmatter (name and description) plus a markdown body of numbered workflow steps, judgment rules, a worked example, and named anti-patterns. The description field acts as the trigger the agent matches against a request, while the body fixes execution order and output format; the skills install via `npx skills add alapha888/agent-skills-en`.

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. 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. 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: git status --short , git diff --cached --stat . If nothing is staged, stop and ask — never invent a message out of nothing. feat , fix , docs , refactor , test , chore . A change that mixes types gets split into two commits, not averaged into one. 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: 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: 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. 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 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.