{"slug": "write-a-skill-md-your-coding-agent-actually-follows-worked-example", "title": "Write a SKILL.md your coding agent actually follows (worked example)", "summary": "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.", "body_md": "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`.\n\nThe catch: a vague skill gets ignored or half-followed. Below is a weak skill, why it fails, and the rewrite.\n\n```\n---\nname: review\ndescription: Helps with code review.\n---\nReview the code carefully and point out any issues. Be thorough.\n```\n\nThree problems:\n\n```\n---\nname: code-review\ndescription: Review a diff or PR for correctness, security and tests; output blocking vs non-blocking findings with file:line and a fix.\n---\n\n## When to use\nUser asks to review a PR, branch, commit range, or staged changes.\n\n## Steps\n1. Get the diff: `git diff <base>...HEAD` or `gh pr diff <n>`. Read the PR description for intent.\n2. For each changed file, read the callers of anything that changed. Never review a hunk in isolation.\n3. 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?).\n4. Run the project's checks from AGENTS.md and note the result.\n\n## Output\nVerdict: approve | request changes\nBlocking:\n- file:line: problem. Why it matters. Suggested fix.\nNon-blocking (max 5):\n- file:line: suggestion.\nChecks run: <command + pass/fail>\n\n## Rules\n- Every finding cites file:line and proposes a concrete fix.\n- If the diff is over 800 lines, say so and review the riskiest files first.\n```\n\nStage 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.\n\nFree 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).\n\n*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.*", "url": "https://wpnews.pro/news/write-a-skill-md-your-coding-agent-actually-follows-worked-example", "canonical_source": "https://dev.to/altros_experiments/write-a-skillmd-your-coding-agent-actually-follows-worked-example-2m86", "published_at": "2026-11-19 16:40:00+00:00", "updated_at": "2026-11-19 16:44:22.715714+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Altros Experiments", "Claude Code", "OpenClaw", "GitHub", "Gumroad"], "also_reported_by": [], "takeaway": "A skill file that names its trigger, orders checks (correctness, then security, then tests) and mandates file:line citations with a suggested fix gets followed, while a generic 'review carefully' prompt gets ignored or half-followed.", "recommendation": {"advice": "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.", "playbook": "coding-agents", "playbook_url": "https://wpnews.pro/playbooks/coding-agents"}, "alternates": {"html": "https://wpnews.pro/news/write-a-skill-md-your-coding-agent-actually-follows-worked-example", "markdown": "https://wpnews.pro/news/write-a-skill-md-your-coding-agent-actually-follows-worked-example.md", "text": "https://wpnews.pro/news/write-a-skill-md-your-coding-agent-actually-follows-worked-example.txt", "jsonld": "https://wpnews.pro/news/write-a-skill-md-your-coding-agent-actually-follows-worked-example.jsonld"}}