AGENTS.md

Instructions for AI coding agents working on this repository. This is about maintaining the library. The skills themselves live in skills/ and are instructions for a different purpose.

What this repository is

A library of Claude Skills for DevOps, SRE and platform engineering. The content is Markdown; the tooling is one dependency-free Python file and a bash installer. There is no build step and nothing to compile.

Before you change anything

./scripts/validate-skills && ./scripts/lint-skills && ./scripts/check-links

All three must pass before and after your change. If they fail before you started, say so rather than fixing unrelated failures silently.

Hard rules

1. Directory name must equal name: in the frontmatter. Claude resolves a skill by its directory name. A mismatch produces a skill that can never load. The validator catches it; do not work around it.
2. Never lower a risk tier to make the validator pass. If validate-skills says a skill mentions a destructive operation and the tier is too low, the correct fix is to raise the tier and write the ### Destructive section — not to remove the command or reword it to dodge the pattern. The rule exists to force the guard rails to be written.
3. Do not add dependencies. scripts/skillkit.py is standard library only, and install.sh is bash 3.2 compatible (the macOS default — no mapfile, no ${arr[@]} on an empty array under set -u). If something seems to need a dependency, it probably needs to be simpler.
4. Regenerate the index after touching skill metadata. ./scripts/generate-index. CI runs generate-index --check and fails on a stale index.
5. Do not invent commands, flags or metric names. Every command in a skill gets copy-pasted into a production terminal by someone under time pressure. If you are not certain a flag exists in the versions the skill claims to support, either verify it or write that it must be verified. An unmarked wrong flag is the worst defect this repository can ship.
6. Do not soften the safety sections. The Destructive subsections are deliberately blunt and repetitive. That is the point.

When editing a skill

• SKILL.md is loaded in full whenever the skill triggers. Every line costs context. Cut anything that does not change what someone does next.
• Every command needs: what it checks, what signal to look for, what the result means. The linter warns when a command block has no explanation on either side.
• The description is the routing mechanism — it is all Claude sees when deciding whether to load the skill. It must name concrete symptoms, including error strings someone would actually type.
• Keep required sections in order: Purpose, Operating Procedure, Investigation, Safety, Verification, Anti-Patterns. The validator enforces both presence and order.
• Bump metadata.version when the content changes materially.

When adding a skill

cp -r skills/_template skills/<category>/<technology>-<job>

Then read docs/skill-authoring.md. Do not skip it — it is short, and the validator implements most of it, so guessing wastes more time than reading.

Check for overlap first. Two skills that each half-cover a topic is worse than one gap, because Claude will load the wrong one. ./scripts/list-skills is the inventory.

When changing the tooling

• scripts/skillkit.py holds every subcommand; the five scripts beside it are one-line wrappers.
• Add a case to tests/run for any new validation rule. Fixtures are built inline there as throwaway repositories, so a new rule is one expect_error call. A rule without a test that proves it fires is not a rule.
• ./tests/run must pass.

Style

• British-neutral technical English. Direct, specific, no marketing language.
• Tables, decision trees and concrete numbers over paragraphs.
• Do not add emoji to skill content. The generated index uses three maturity markers; that is all.

What not to do