1实现原理 · 为什么它能做到

纯「参考文档」型 skill，无任何可执行脚本/工具调用/网络请求——功能全部靠「被 agent 读进上下文后改变其写作行为」实现，对写作者（人或 agent）起尺子作用，不起执行器作用。

skills/productivity/writing-for-agents/SKILL.md

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.

定位即机制：git ls-tree 证实该 pin 下目录只有 3 个文本文件（2 个 .md + 1 个 3 行 .yaml），没有任何代码。它宣称的『让 agent 文档可预测』靠的是读者（agent）内化其行文法则，而非任何自动化。

触发机制是模型自动调用（model-invoked）：frontmatter 保留 description 且未设 disable-model-invocation，description 即技能最顶层的 context pointer，其措辞决定 agent 何时取用该材料。

skills/productivity/writing-for-agents/SKILL.md

description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

SKILL-MECHANICS.md 定义：model-invoked 的机制就是『omit disable-model-invocation, and write a model-facing description』，本技能 frontmatter 恰好如此，是它自己理论的自我应用。description 只列了两个触发分支（写 skill、改 AGENTS.md/CLAUDE.md），正文范围却宽得多——按它自己的 pointer 经济学，常驻 description 的每个词都花 context load，所以只留最高价值分支。

采用渐进披露结构：技能专属内容（frontmatter、invocation 选择、router skills）拆到 SKILL-MECHANICS.md，仅当要写的是 skill 时才经相对链接取用，压低主文件的常驻负载。

skills/productivity/writing-for-agents/SKILL.md

When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.

这是它教的内容的 dogfood：SKILL-MECHANICS.md 首句自称『The skill-specific branch of writing-for-agents』，即信息层级里第 3 档『disclosed reference』——放在主文件之外、由 pointer 按需触发。

核心行为锚点是『leading word』：刻意选用模型预训练中已存在的概念词（_lesson_、_fog of war_、_tracer bullets_）作为单 token 行为锚，重复 token 而不重复句子，用最少 token 调动模型已有先验来固定一片行为区域。

skills/productivity/writing-for-agents/SKILL.md

A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.

并配套『negation 反模式』：禁止式措辞会把被禁行为拖进上下文反而更可用（_Don't think of an elephant_），故主张只 prompt 正面目标行为。

剪枝判据是行为主义的 no-op 测试而非篇幅美学：一句指令若模型默认就遵守，就是付了 load 却啥也没说的 no-op，删除时应整句删除；两句分歧以『跑一遍文档看行为变没变』裁决，不以辩论裁决。

skills/productivity/writing-for-agents/SKILL.md

Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test (does it change behaviour versus the default?) is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it.

同一节还给出 duplication / sediment / sprawl 等失败模式词汇——skill 的用途一半在评审已有文档，用这套词汇当诊断工具。

用『两负载』（context load 与 cognitive load）作为统一决策经济学，把拆分/内联/披露/pointer 措辞等所有写作决策化约为同一个权衡的不同位置。

skills/productivity/writing-for-agents/SKILL.md

**Context load** is the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires. / **Cognitive load** is the cost on the human: which documents exist and when to reach for each. The human is the index.

配套『信息层级』阶梯（in-file step → in-file reference → disclosed reference）决定每块内容放多深；『completion criteria』（clarity+demand）与『post-completion steps』机制解释 agent 为何会 premature completion 以及怎么防。

2核心能力

01撰写/评审任何 agent 消费的文档：skill、AGENTS.md/CLAUDE.md、pointer 指向的文档

02设计 context pointer 措辞与触发分支（front-load、一分支一触发、砍掉正文已含的标识）

03用信息层级决定内容归属层，做渐进披露（progressive disclosure）与同标题聚合（co-location）

04设计 completion criteria（clarity/demand）防御 premature completion，管理 legwork 强度

05决策何时拆分文档：按序列拆（藏住后续步骤）与按 invocation 拆

06提炼 leading word 压缩 token 并锚定行为；避开 negation 反模式

07逐句剪枝：single source of truth、相关性、no-op 测试，清除 duplication/sediment/sprawl

08（子技能，SKILL-MECHANICS）选择 model-invoked vs user-invoked、设计 router skill 收纳记忆负担

4管控建议与判定依据

建议配套管控措施

面向 Agent

可自动加载

面向管理者

登记来源与版本

判定依据（文件路径与关键语句摘要）

SKILL.md: 纯提示词指令与规则文本，无脚本执行与外部影响

审计说明： 全目录仅 3 个静态文本文件（SKILL.md / SKILL-MECHANICS.md / agents/openai.yaml），git ls-tree 证实无脚本、无二进制、无隐藏文件、无符号链接；对 3 文件全文 grep http/curl/exec/$( 零命中，无网络调用、无凭证读取、无自写文件；纯咨询性参考内容，无执行面，风险仅来自使用场景。

5第二遍独立确认

[ok] 外部资源/工具 = 无（技能文件内零 CLI/API/网络端点） — 对 SKILL.md、SKILL-MECHANICS.md、agents/openai.yaml 全文 grep 'http://|https://|curl|subprocess|exec\(|\$\(' 无命中（exit=1）。docs/productivity/writing-for-agents.md 含 aihero.dev 外链，但该页属仓库人类阅读的文档树（AGENTS.md L17：docs 树镜像、URL https://aihero.dev/skills-<skill-name>），不随技能安装、不被 agent 作为技能内容读取，不计入技能外部依赖。
[ok] 安全结论 green：无脚本、无网络、无凭证、无写文件 — git ls-tree -r HEAD skills/productivity/writing-for-agents/ 恰好 3 个文件（SKILL.md、SKILL-MECHANICS.md、agents/openai.yaml），无隐藏文件/脚本/二进制/符号链接；openai.yaml 仅 3 行 interface 文本。反例搜索无发现。
[ok] model-invoked 声称（description 在、无 disable-model-invocation） — SKILL.md frontmatter 复核：有 description 行、无 disable-model-invocation 键；与 SKILL-MECHANICS.md L9 给出的 model-invoked 机制定义（omit disable-model-invocation + model-facing description）完全一致。
[ok] SKILL-MECHANICS.md 经相对 pointer 披露且文件真实存在 — SKILL.md L8 相对链接 SKILL-MECHANICS.md，目标文件在该 pin 树内存在（ls-tree 证实），SKILL-MECHANICS.md 首句反向链回 SKILL.md，互指闭合。
[ok] 『leading word 调动预训练先验』是否夸大 — 复核原文：主张以『compact concept already living in the model's pretraining』锚定行为，属行文设计主张而非可执行承诺；全文件没有任何自动化/eval/可测产出声称（docs 页反而自述 'There is no automated eval here'），无吹牛。
[ok] description 范围（skill/AGENTS.md/CLAUDE.md）与正文范围（一切 agent 文档）的出入 — 非缺陷：按该 skill 自己的 pointer 经济学（常驻 description 每个词都花 context load、pointer 措辞决定触发），收窄分支是刻意设计；docs 页明示其余场景 'Reach for it by hand'，人可随时输入技能名。
[ok] 更名史（writing-great-skills → writing-for-agents, v1.1） — docs/productivity/writing-for-agents.md（同 pin 仓库内）：'It was called `writing-great-skills` until v1.1.' 及 'There is no alias. Reinstall under the new name.'；技能目录内 SKILL.md 未提别名，与『无 alias』一致。克隆为浅克隆（depth=1），无法用 git log 交叉验证 rename commit。
[ok] stars/许可证/推送时间元数据 — GitHub API 两次拉取一致：stargazers_count 253950、license MIT（仓库 LICENSE 文件头 'MIT License / Copyright (c) 2026 Matt Pocock'）、pushed_at 2026-09-04T08:45:43Z（与 pin commit 时间 2026-09-04 09:43:27+0100 同一天）。注意：仓库创建于 2026-02-03，星标为 2026-09-06 快照，仅对该时点有效。

6结论

文类定义级理论密度：两负载、信息层级、leading word、no-op 测试都是可迁移到任何 agent-facing 文档的洞见，不绑定具体工具链

零执行面、极低成本：3 文件共 106 行、无脚本无依赖，作为 model-invoked 参考只花 description 那一条常驻 load

自身即示范：用渐进披露拆 SKILL-MECHANICS.md、用收窄 description 做 pointer，理论自洽并可被读者直接观察

生态位独特（meta-skill）：作为仓库写作标准层存在，作者自称仓库每个 skill 都按它写成

文档页透明披露边界：明说无自动化 eval、check 靠 manual run，不夸大能力

适合： 想系统性提升『写给 agent 的文档』质量的个人作者与团队：维护 AGENTS.md/CLAUDE.md 或技能库的人、agent 技能作者、需要评审既有长文档是否臃肿的人（review pass 是其高价值场景）。适合在动手前当尺子、写完后当诊断词汇表。

不适合： 需要开箱即用模板/清单式写作助手、希望『让 agent 帮我写』的自动化产出者（docs 页明言模型默认产出冗长文本，须人对草稿套用本参考）；需要可机检指标/CI 校验的团队（作者自称无自动化 eval）；内容仅供人类阅读、不经任何 agent 消费的纯文档（会 over-engineering）。

Install Agent-Ready

① Verified Mirror 2026-09-06

Option A · Direct DownloadDownload writing-for-agents.tar.gz

sha256: 2741c227a60b8035…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 3cca18b368.