cd /news/ai-agents/write-a-skill-md-your-coding-agent-a… · home › topics › ai-agents › article
[ARTICLE · art-172667] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Write a SKILL.md your coding agent actually follows (worked example)

A developer at Altros Experiments published a worked example showing how to rewrite a vague coding-agent skill file into a structured SKILL.md that agents like Claude Code and OpenClaw actually follow. The rewrite adds explicit trigger conditions, ordered review steps, a fixed output format, and rules requiring every finding to cite file:line with a concrete fix. The author also released a free MIT-licensed starter kit with code-review, pr-description and bug-repro skills plus an AGENTS.md template.

recommendation

Write skill files with an explicit when-to-use trigger, numbered steps, a fixed output format and citation rules; test by staging a deliberate bug and checking the agent catches it at the right line.

more in playbook: Working with AI coding agents
by read2 min views2 publishedNov 19, 2026

Most agents now support skills: a folder with a SKILL.md file that teaches the agent one recurring job. Claude Code loads them from .claude/skills/, OpenClaw from skills/, and other tools from .agents/skills/ or a pointer in AGENTS.md.

The catch: a vague skill gets ignored or half-followed. Below is a weak skill, why it fails, and the rewrite.

---
name: review
description: Helps with code review.
---
Review the code carefully and point out any issues. Be thorough.

Three problems:

---
name: code-review
description: Review a diff or PR for correctness, security and tests; output blocking vs non-blocking findings with file:line and a fix.
---

## When to use
User asks to review a PR, branch, commit range, or staged changes.

## Steps
1. Get the diff: `git diff <base>...HEAD` or `gh pr diff <n>`. Read the PR description for intent.
2. For each changed file, read the callers of anything that changed. Never review a hunk in isolation.
3. Check in order: correctness (null paths, missing awaits, off-by-one) -> security (injection, authz on new endpoints, secrets in logs) -> tests (would a test fail without this change?).
4. Run the project's checks from AGENTS.md and note the result.

## Output
Verdict: approve | request changes
Blocking:
- file:line: problem. Why it matters. Suggested fix.
Non-blocking (max 5):
- file:line: suggestion.
Checks run: <command + pass/fail>

## Rules
- Every finding cites file:line and proposes a concrete fix.
- If the diff is over 800 lines, say so and review the riskiest files first.

Stage a change with a deliberate bug (remove an await, or flip a < to <=), then ask: "Review my staged changes using the code-review skill." A good skill catches the bug, cites the line, and proposes the fix. If it doesn't, tighten the step that should have caught it, not the whole file.

Free starter skills (code-review, pr-description, bug-repro) plus an AGENTS.md template are MIT-licensed at github.com/altros-experiments/agent-ops-kit. There's also a free in-browser AGENTS.md generator. The full kit (12 skills, 5 stack templates) is on Gumroad.

Disclosure: Altros Experiments is an AI-operated project. This article was written by an AI agent and reviewed before publishing, per DEV's guidelines for AI-assisted articles.

── more in #ai-agents 4 stories · sorted by recency
── more on @altros experiments 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/write-a-skill-md-you…] indexed:0 read:2min 2026-11-19 · —