writing-for-agents
For skills, standing agent instructions, recorded rules, or documents agents skip, write and prune reliable triggers and checkable steps. Use to author or revise SKILL.md, AGENTS.md, CLAUDE.md, rules and references, or diagnose unreliable invocation and skimming.
timharris707 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add timharris707/skills --skill writing-for-agents技能说明
name: writing-for-agents description: "For skills, standing agent instructions, recorded rules, or documents agents skip, write and prune reliable triggers and checkable steps. Use to author or revise SKILL.md, AGENTS.md, CLAUDE.md, rules and references, or diagnose unreliable invocation and skimming."
Writing for Agents
Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.
Every document an agent reads is a behavior lever, not prose. The packaging differs across a skill, a standing instruction file, and a reference reached by a pointer, but the writing does not: the same levers make each one predictable. Predictable means the agent takes the same process every run. It does not mean the agent produces the same output.
This skill is reference, not a sequence: consult the rung that matches what you're writing. For frontmatter, invocation modes, and this repo's catalog invariants, read references/skill-mechanics.md. When the reader is a human, as on a landing page, a README's front half, or a launch post, these levers read cold; use writing-for-humans instead.
Context pointers
An agent often holds a short line that points at material it has not loaded: a skill's description, or a line in AGENTS.md naming a doc. That line is a context pointer: a reference the agent already holds that names material it does not, plus the condition for going and getting it.
The pointer's wording, not its target, decides whether the agent reaches the material. A must-have target behind a weakly worded pointer is a variance bug: the material is right and the firing is a coin flip. Sharpen the wording first; inline the material only when sharpening has already failed.
A pointer does two jobs: say what the material is, and name the branches that should trigger reaching it. A branch is a distinct case the document handles: different runs take different paths through it. Because an always-loaded pointer costs on every turn, it earns harder pruning than the body:
- Front-load the trigger. The pointer's opening words are where it does its work.
- One trigger per branch. Synonyms that rename a single branch are one branch written twice.
- Cut identity the body already carries. The pointer says when to come, not who you are.
The two budgets
Every document and every pointer spends one of two budgets:
- Context load. Always-loaded material occupying the window: a skill description, an
AGENTS.mdline, anything present every turn whether or not it fires. Paid in tokens and in attention. - Cognitive load. The cost on the human: knowing which documents exist and when to reach for each. The human is the index.
Cognitive load is not a cost to minimize. It is the price of human agency: spend it where human judgment matters, remove it where it does not. Material behind a pointer escapes context load at the price of the pointer's own line; material with no pointer rides entirely on cognitive load.
The information hierarchy
A document mixes two content types: steps (ordered actions the agent performs) and reference (definitions, rules, and facts consulted on demand). A document may be all steps, all reference, or both. The decision that matters is where each piece sits on a ladder ranked by how immediately the agent needs it:
- In-file step. The primary tier: what the agent does, in order.
- In-file reference. Consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung). That is an arrangement, not a smell.
- Disclosed reference. Pushed into a separate file behind a pointer, loaded only when the pointer fires. Ranges from a sibling in
references/to material any document can point at.
Push too little down and the top bloats; push too much and you hide what the agent actually needs. That tension is the whole decision.
Progressive disclosure is the move down the ladder. It is not primarily a token optimization. It is how the top stays legible. The cleanest test is branching: inline what every branch needs, disclose what only some branches reach. When a document has steps, undisclosed in-file reference buries them, and attending to them becomes a coin flip.
Co-location is the within-file companion. The ladder decides how far down a piece sits; co-location decides what sits beside it once there. Keep a concept's definition, rules, and caveats under one heading so reading one part brings its neighbors along. Scattering fragments one meaning across many places; duplication, a distinct failure, repeats one meaning in two.
Sprawl is the failure mode: a document simply too long, even when every line is live and unique. Attention thins across the excess. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
Completion criteria
Every step ends on a completion criterion, the condition telling the agent the work is done. Two properties make it a lever:
- Clarity. Can the agent tell done from not-done? A vague bound ("understanding reached") invites premature completion: ending early as attention slips toward being done. Visible later steps supply the pull; the criterion's clarity is the resistance. Sharpen the bound first; it is local and cheap. Only when a bound is irreducibly fuzzy and you observe the rush should you hide later steps by splitting the sequence, and hiding works only across a real context boundary (a handoff, a subagent dispatch). An inline call leaves the later steps in context and clears nothing.
- Demand. How much the criterion requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives the digging the agent does inside the work, and it is not step-bound: "every rule applied" b