Force the agents-md skill before any AGENTS.md write

[j0ntz]

Description

An AGENTS.md is loaded into every session for its repo, so a careless one taxes every future task there, and it fails silently rather than loudly. The usual failure is the confident first draft: a directory listing, pasted code snippets, and style rules the linter already enforces. Measured, that file performs worse than having no file at all.

This adds a skill/gate pair so the guidance is unavoidable at the moment it matters.

• .cursor/skills/agents-md/SKILL.md — the guidance: the size budget, the WHAT/WHY/HOW to include, the exclude list (directory listings, style rules, task-specific instructions, auto-generated or doc-duplicating content), progressive disclosure, pointers over pasted code, and a pre-save checklist. Distilled from philschmid.de/writing-good-agents and cached in the skill, so applying it never depends on a fetch.
• agent-watcher/hooks/require-agents-md-skill.sh (PreToolUse) — blocks writes to any AGENTS.md, in any repo, until the skill is loaded that session. Covers both authoring vectors: Write/Edit by file_path, and Bash by redirect/tee/heredoc. Bash reads (cat, grep, wc) still pass.
• agent-watcher/hooks/mark-agents-md-skill-read.sh (PostToolUse) — clears the gate on a Skill call, a Read of the SKILL.md, or a Bash reference to it.
• claude-settings/hooks.json — registers both, plus the rubric-drift lock (the skill is excluded from rubric coverage: it is repo-authoring tooling, not part of the one-shot delegation chain).

The marker is session-keyed rather than task-keyed, so this also covers interactive edits outside orchestrated runs. The gate is not one-bounce: it blocks until the skill is loaded, and the remedy is a single call.

Testing

• 12 synthetic stdin vectors against both hooks: Write/Edit on AGENTS.md (nested paths and case variants) blocked; README.md passes; Bash >, >>, tee, tee -a, and heredoc into an AGENTS.md blocked; Bash cat/grep/wc reads pass; marker set by each of the Skill, Read, and Bash paths and by none of the unrelated ones.
• End to end in a live session after installing: with the marker cleared, a Write to an AGENTS.md was blocked by the hook with its guidance message; a Skill call to agents-md set the marker; the same write then succeeded.
• First consumer: the AGENTS.md added in Add swaps.xyz swap provider edge-exchange-plugins#480 was rewritten against this skill, 117 → 68 lines (dropped the directory listing, the pasted factory snippet, and the style rules).

Asana: https://app.asana.com/0/1215088146871429/1217036054017879