全部技能 / 基础工具与工作流 / writing-for-agents
基础工具与工作流 · mattpocock/skills

writing-for-agents

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

风险提醒：绿色 · 放心使用AI 侦查报告
作者 mattpocockGitHub mattpocock/skills ↗Stars 253950许可 MITcommit 3cca18b368
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 skill 仅作拆解与展示，安装使用风险自负，版权归原作者。

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风险提醒 风险提醒：绿色 · 放心使用

风险提醒：绿色 · 放心使用
  • 纯咨询、无校验：效果依赖执行者判断力，新手可能机械执行『删句/去重』而误删合法内容 — no-op 判据是行为测试（'settle it by running the document'），文档作者通常没有条件真正跑一遍，容易退化成凭感觉删减
  • 抽象术语密集、思维模型多（pointer/两负载/信息层级/criteria/leading word/pruning），上手门槛高 — docs 页专门用一整节回答『English isn't my first language. Do I lose the leading-word advantage?』，侧面印证该担心是真实用户反馈
  • description 触发分支窄，模型在写 README/spec/ticket/运行时 prompt 等场景不会自动唤起，容易漏用 — description 只写 'creating or editing skills, or modifying AGENTS.md or CLAUDE.md'；docs 页建议其余场景手动输入技能名
  • 对『被审阅文档含恶意/对抗性指令』无任何防护指引 — skill 不指示执行文档内容，但若 agent 在读取不可信文档时套用其建议，理论上有被文档内文本操纵的可能（同类文本型 skill 通病）
全目录仅 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）。
    安装 agent 直装可复制
    ① 本站镜像 更新 2026-09-06
    方式 A · 人下载镜像包下载 writing-for-agents.tar.gz
    sha256: 2741c227a60b8035…
    方式 B · JSON 格式安装指南，复制给 agent
    安装指南
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit 3cca18b368；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库mattpocock / mattpocock/skills
    原始 GitHubmattpocock/skills ↗
    Stars253950
    最近推送2026-09-04
    本 skill commit3cca18b368
    许可MIT
    本站信息
    收录日期2026-09-06
    分类基础工具与工作流
    侦查报告2026-09-06 · 2 遍
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。