{"slug": "how-to-write-your-first-agent-skill", "title": "How to Write Your First Agent Skill", "summary": "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`.", "body_md": "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.\n\nThe 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.\n\nA skill is a folder containing one file: `SKILL.md`. It has two parts.\n\nThe 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.\"\n\nThe body is plain markdown: the workflow, the rules, an example. No code, no config beyond the frontmatter.\n\nThe smallest skill in my pack generates commit messages, and it shows every part doing a job. Its frontmatter, verbatim:\n\n```\n---\nname: git-commit-message\ndescription: \"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.\"\n---\n```\n\nThe workflow is five numbered steps, in execution order:\n\n`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.\nThen come the rules that encode judgment — the things you would otherwise keep correcting in review:\n\nAnd one worked example, with the expected output:\n\n```\ngit 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.\"\n```\n\nFinally, the anti-patterns — the failure modes, named explicitly:\n\nEach 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.\n\nDrop 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.\n\nRepo: [https://github.com/alapha888/agent-skills-en](https://github.com/alapha888/agent-skills-en)\n\n```\nnpx skills add alapha888/agent-skills-en\n```\n\nThe structure is the stable part; the rules are yours. Take the workflow you explained three times this week, and write it down once.", "url": "https://wpnews.pro/news/how-to-write-your-first-agent-skill", "canonical_source": "https://dev.to/alapha888/how-to-write-your-first-agent-skill-ab6", "published_at": "2026-10-06 01:22:06+00:00", "updated_at": "2026-10-06 01:48:04.096616+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "generative-ai"], "entities": ["alapha888", "agent-skills-en", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-write-your-first-agent-skill", "markdown": "https://wpnews.pro/news/how-to-write-your-first-agent-skill.md", "text": "https://wpnews.pro/news/how-to-write-your-first-agent-skill.txt", "jsonld": "https://wpnews.pro/news/how-to-write-your-first-agent-skill.jsonld"}}