skills AGENTS.md

Agent Skill Authoring Conventions

Rules specific to writing skills for this repository. For global agent behavior, see the global-rules skill. These conventions follow the writing-great-skills framework: a skill exists to make the agent take the same process every run. Predictability is the goal every rule below serves.

Meta-Rule: Draft Before Writing

Never write a skill file without explicit user confirmation.

1. Propose a plan (name, location, flags, structure)
2. Wait for user to say "yes" or request changes
3. Only then write the SKILL.md file

This applies to every skill, no exceptions.

Meta-Rule: Update README

After writing a new skill, update README.md before committing.

1. Add the skill to the quickstart invocation list.
2. Add a failure mode entry in ## Why These Skills Exist if applicable.
3. Add a row to the ## Reference table with name, link, description, and flags.

Do not commit the skill without the README update.

Meta-Rule: Self-Check Before Committing

Before committing any skill addition or update, verify every rule below by reading the files. There is no validator script; you are the check.

For every skill you touched:

1. name, present in frontmatter, kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$), 64 chars or fewer, and exactly matches the skill's directory name.
2. description, present and 1024 characters or fewer.
3. SKILL.md length, 100 lines or fewer.
4. README coverage, the skill appears in the README.md quickstart list (as /<name>) and has a row in the ## Reference table linking ./skills/<name>/SKILL.md.
5. Markdown links resolve, every real .md path linked or backticked in SKILL.md points to a file that exists. Ignore template paths containing <...> placeholders.

Fix every failure before committing. Do not commit until all five pass.

---

Project Structure

• Skills live in skills/<name>/SKILL.md (project-level)
• Never use .agents/skills/ for this repo
• Each skill is a directory containing SKILL.md at minimum
• Optional: REFERENCE.md, references/, assets/