# How to Write Your First Agent Skill

> Source: <https://dev.to/alapha888/how-to-write-your-first-agent-skill-ab6>
> Published: 2026-10-06 01:22:06+00:00

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.