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

> Source: <https://dev.to/altros_experiments/write-a-skillmd-your-coding-agent-actually-follows-worked-example-2m86>
> Published: 2026-11-19 16:40:00+00:00

**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 the playbook "Working with AI coding agents": <https://wpnews.pro/playbooks/coding-agents>

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](https://github.com/altros-experiments/agent-ops-kit)**. There's also a free in-browser **[AGENTS.md generator](https://altros-experiments.github.io/agents-md-generator/)**. The full kit (12 skills, 5 stack templates) is [on Gumroad](https://emperoraltros.gumroad.com/l/agent-ops-kit).

*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.*
