When writing documents that AI reads and follows, such as Agent Skills, CLAUDE.md, and AGENTS.md, follow the criteria below. These are common principles for the kuden:agent-skill skill and the kuden:persistent-instructions skill; criteria specific to Agent Skills are in the kuden:agent-skill skill, and criteria specific to rule documents are in the kuden:persistent-instructions skill.
Principle 1. The reader is a smart model
The one reading and executing the document is a model that can read context and make its own judgments. Write only things that the model cannot reach by inference. This includes policies specific to the project or author, hidden constraints, assumptions not visible from the outside, and gotchas that cannot be known without trying.
- Do not defensively spell out judgments that can be understood by thinking. Do not add exclusion clauses for edge cases or caveats to prevent misreading
- Do not design for models with low reading comprehension. A model that cannot read context cannot perform the other work the document requires either
- If the purpose can be achieved with a procedure or example, do not write background explanation. This includes incident stories and explanations of outcomes to avoid. Do not write reasons that can be understood by thinking, such as general properties of git
- Do not write metaphors. The reader infers other aspects of the metaphor, making the meaning of the sentence ambiguous
Principle 2. Write only things aimed at the executing model
Write the history of why that method was chosen, and the options that were tried and rejected, in the commit message or PR description.
Principle 3. When editing, aim for the best as a whole
When modifying an existing document, do not try to keep the diff small. Rather than appending the added content to the end of an existing section, think about how it would have been written if that content had been there from the start. You may significantly change the structure.
Principle 4. Accepting or rejecting review feedback
Feedback from external Agents or subagents, even if factually correct, is not necessarily worth writing in the document. Apart from verifying whether the feedback is correct, decide whether to accept it using the following questions.
- Question 1. Is it not something a smart model could judge on the spot?
- Question 2. Is it not something that the principles specific to the target document type have determined not to write?
- Question 3. Is it not aimed at future editors rather than the executing model?
- Question 4. Is it not something without which the model would get stuck in execution?
Do not accept feedback that falls under Questions 1 through 3. Accept feedback that falls under Question 4.
Report feedback that was not accepted to the user with the reason.