writing-for-agents
Reference for writing any document an agent consumes: a skill, an AGENTS.md / CLAUDE.md, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same process every run rather than producing the same output.
When the document you're writing is a skill, read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills.
Permission to change guidance
Never edit AGENTS.md, CLAUDE.md, or equivalent agent instructions, skills, rules files, or documents that establish
best practices and conventions without the user's explicit permission for a concrete change. This includes referenced
guidance documents, regardless of their filename or location. Creating, deleting, renaming, or moving such guidance
also requires explicit permission for that action.
A request to read, review, audit, discuss, or recommend improvements is not permission to change these files. Permission to implement a product feature or fix a bug does not authorize updating its governing instructions or conventions as a side effect. Do not treat a general desire to improve the setup as approval for unspecified edits.
If the user has already specified the concrete change and authorized it, proceed within that scope without asking again. Otherwise, first present the affected files and the proposed wording or specific changes for review, then obtain explicit approval before modifying them. Permission for one change does not extend to unrelated cleanup or new rules.