/writing-for-agents 技能

它的作用

writing-for-agents is the reference for writing agent-facing documents: a skill, an AGENTS.md or CLAUDE.md，一个 spec，运行时提示词、README、任何 agent reads. The format differs, but the writing does not. The same levers make each one predictable, so the agent follows the same process on every run (not necessarily to the same output).

Its default fix is to delete, not to explain. Ask an agent to write instructions for another agent and it spends most of its words explaining what the model already knows. Each of those lines is a no-op: it costs context and changes no behaviour. This reference helps you find them, so it is as useful on a document you already have as on a blank file.

它曾叫 writing-great-skills until v1.1. The new name fits what it always was. Almost none of it is specific to skills. The skill-only mechanics (frontmatter, the model- versus user-invoked choice, router skills) live in a linked SKILL-MECHANICS.md that you read only when the document in front of you is a skill.

何时使用

输入 /writing-for-agents，或当你在创建或编辑技能、修改 AGENTS.md or CLAUDE.md.

其余智能体阅读的一切，都手动使用它：你的文档、规格说明和 tickets，系统与 AFK prompts. The test is one question: does an agent read this? It does not matter how the agent gets the document: a pointer names it, a human pastes it, or it is in the repo. To find out what a codebase contains, use grill-with-docs. This reference controls how a document reads, not what it knows.

两种负载

The central idea is two budgets that every document and pointer spends:

上下文负载: the cost of always-loaded material on the agent's window: an AGENTS.md 行、技能描述、任何每时每刻都待在上下文里的东西，轮次无论它是否触发。
认知负荷: the cost to you of remembering which documents exist and when to reach for each. You are the index. Do not try to minimise this cost, because it is the price of human agency.

Once you think in these two loads, most authoring decisions (split or don't, inline or disclose, point or push) become the same trade made in different places.

杠杆

上下文指针: the reference held in context that names out-of-context material and encodes when to reach it. A skill description and an AGENTS.md line naming a doc are the same thing. The pointer's wording, not its target, decides how reliably the agent follows it.
信息层级: the ladder from in-file step, to in-file reference, to disclosed reference behind a pointer. 渐进披露 is moving material down that ladder so the top stays easy to read.
完成标准: how clear and demanding each step's done-condition is, and the legwork that demand causes. They are the defence against 过早完成.
首词: a compact concept already in the model's pretraining (tight, red, 曳光弹) that the agent thinks with while running the document. It works in two places. In the body it guides execution, and in the pointer it triggers invocation.
修剪: single source of truth, relevance, and the no-op test applied sentence by sentence, against duplication, sediment and sprawl.

常见问题

原来的 /writing-great-skills 去哪了？ It is this skill, renamed in v1.1. Users pointed it at AGENTS.md, docs, specs, tickets and runtime prompts long before the rename. Structure, leading words and pruning apply to any text an agent reads. There is no alias. Reinstall under the new name.

"Writing for agents": so the agent does the writing? The other way round. You are the author; the agent is the reader. That is what makes it hard. You write for a reader that has already read everything, so explanation is waste and precision is the whole job.

我不能直接让智能体替我写吗？ You can, and it will produce something verbose. Left alone the model explains what it already knows, and it will not apply the no-op test or reach for a leading word on its own. Use the reference to review the draft. Most of its value comes from that review pass.

我让智能体精简文档，它把功能也删了。 Agents told to "streamline" optimise for length, because length is the thing they can see. The no-op test checks behaviour, not style: delete the line and ask whether the agent's behaviour changed. When a sentence fails, delete the whole sentence rather than trim words from it, and settle a disagreement about it by running the document, not by arguing.

我怎么知道它什么时候完成？ When it works, and you can no longer find duplication, sediment or no-ops. There is no automated eval. You check by running the document by hand and using the failure-mode vocabulary to diagnose problems. When a document misbehaves, the same vocabulary helps you fix it: name the failure mode first, then fix that.

这个应该放在 CLAUDE.md 或别的地方？ 问清你想支付哪种负载。 CLAUDE.md 加载进每个会话 unconditionally. Material behind a pointer costs only the pointer's own line until it fires. Anything that applies in one session out of ten costs context load in the other nine.

我需要为每个新模型重写文档吗？ Mostly no, and over-fitting to one model causes its own problems. Updating for a new model is usually another no-op pass rather than a rewrite.

我的技能只在构建它的那个具体任务上有效。 The common method (do the work once, then have the agent write it up as a skill) fits that one run too closely, and the examples come out too specific. Keep the run as evidence, then generalise on purpose: strip what belonged to that repo and those files, and write for the class of task.

英语不是我的母语。我会失去「首词」优势吗？ No. Finding the word that packs the most behaviour into the fewest tokens is work the reference does for you.

做到以下就算成功

文档越好越短，你会惊讶于剩下多少。
You can point at a leading word and see it change the agent's behaviour in more than one place.
任何形式的内容都不会陈述两次。重复是文档从未被测试过的最可靠标志。
只有一个分支需要的参考放在指针后面，而不是在主文件里。

在流程中的位置

This is a reach-for-it-anytime standalone reference. It applies to the whole set, not to one skill. Every skill here was written with it, and it also covers the documents the other skills produce (a GLOSSARY.md and its ADRs, a spec, a ticket) once an agent has to read them. Its one direct caller is retro, which loads it before proposing any steering file or skill. When you're unsure which skill or flow fits a task, ask-matt 为你规划整套流程。