Home / All Skills / Workflow & Core Tools / writing-for-agents
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · mattpocock/skills

writing-for-agents

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

L1 Basic · Source registration onlyV1 Commit-PinnedDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 253950License MITCommit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

A pure 'reference document' skill without any executable scripts, tool calls, or network requests—its entire functionality is realized by 'altering the agent's writing behavior once read into context', acting as a measuring ruler for the author (human or agent) rather than an executor.

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.
Positioning as mechanism: git ls-tree confirms this pin directory contains only 3 text files (two .md files + one 3-line .yaml file) with zero code. Its claim of 'making agent documents predictable' relies entirely on the reader (agent) internalizing its stylistic rules rather than any automation.

Trigger mechanism is model-invoked: frontmatter retains description without setting disable-model-invocation; description acts as the top-level context pointer of the skill, and its phrasing dictates when the agent retrieves the material.

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 defines: the model-invoked mechanism is to 'omit disable-model-invocation, and write a model-facing description', which is precisely how this skill's frontmatter is configured—a self-application of its own theory. The description lists only two trigger branches (writing skills, modifying AGENTS.md/CLAUDE.md), whereas the body scope is much broader—under its own pointer economics, every word in a resident description incurs context load, so only the highest-value branches are kept.

Employs a progressive disclosure structure: skill-specific content (frontmatter, invocation choices, router skills) is split out into SKILL-MECHANICS.md and retrieved via relative links only when authoring a skill, keeping the resident load of the main file low.

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.
This is dogfooding what it teaches: the opening sentence of SKILL-MECHANICS.md declares itself as 'The skill-specific branch of writing-for-agents', representing tier 3 in the information hierarchy ('disclosed reference')—placed outside the main file and triggered on-demand via pointers.

The core behavioral anchor is the 'leading word': deliberately selecting pre-existing concept words from the model's pretraining (_lesson_, _fog of war_, _tracer bullets_) as single-token behavioral anchors, repeating tokens instead of sentences to evoke existing model priors with minimal tokens to pin down a behavioral zone.

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.
Paired with the 'negation anti-pattern': prohibitive phrasing pulls the forbidden behavior into the context, paradoxically making it more accessible (_Don't think of an elephant_), thus advocating prompt engineering focused solely on positive target behaviors.

Pruning criteria rely on a behaviorist no-op test rather than aesthetic length: if a model follows an instruction by default, that instruction is a no-op that incurs context load while accomplishing nothing, and it should be removed entirely; discrepancies between sentences are settled by 'running the document to see if behavior changes', not by debate.

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.
The same section provides vocabulary for failure modes such as duplication / sediment / sprawl—half of this skill's utility lies in reviewing existing documents using this vocabulary as diagnostic tools.

Uses 'two loads' (context load and cognitive load) as a unified decision economics framework, reducing all writing decisions—such as splitting, inlining, disclosure, and pointer phrasing—to different trade-off positions along the same spectrum.

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.
Paired with an 'information hierarchy' ladder (in-file step → in-file reference → disclosed reference) to determine content depth; mechanisms like 'completion criteria' (clarity + demand) and 'post-completion steps' explain why agents hit premature completion and how to prevent it.

2Core Capabilities

01Author/review any agent-consumed documents: skills, AGENTS.md/CLAUDE.md, and pointer-referenced documents
02Design context pointer phrasing and trigger branches (front-loading, one branch per trigger, pruning markers already contained in the body)
03Determine content tiers using the information hierarchy, applying progressive disclosure and co-location under shared headers
04Design completion criteria (clarity/demand) to guard against premature completion and manage legwork intensity
05Decide when to split documents: sequential splitting (hiding downstream steps) vs. invocation-based splitting
06Distill leading words to compress tokens and anchor behavior; avoid negation anti-patterns
07Perform sentence-by-sentence pruning: single source of truth, relevance, no-op testing, eliminating duplication/sediment/sprawl
08(Sub-skill, SKILL-MECHANICS) Choose model-invoked vs. user-invoked; design router skills to absorb memory burdens

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Can be auto-loaded
For Administrators
Register source and version
Evidence & Triggers (File Paths & Excerpts)
  • SKILL.md: Pure prompt instructions and rule text; no script execution or external impact
Audit Notes: The entire directory contains only 3 static text files (SKILL.md / SKILL-MECHANICS.md / agents/openai.yaml); git ls-tree verifies no scripts, binaries, hidden files, or symlinks; full-text grep across all 3 files for http/curl/exec/$( yields zero hits, with no network calls, credential access, or file-writing operations; purely advisory reference content with zero execution surface; risk stems solely from usage context.

5Second-Pass Verification

  • [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 快照，仅对该时点有效。

6Verdict & Scenarios

  • Genre-defining theoretical density: two loads, information hierarchy, leading words, and no-op testing are transferable insights for any agent-facing document, decoupled from specific toolchains
  • Zero execution surface, extremely low overhead: 3 files totaling 106 lines, no scripts or dependencies, incurring only the single resident load of the description as a model-invoked reference
  • Exemplifies its own teachings: uses progressive disclosure to split SKILL-MECHANICS.md and a narrowed description as a pointer, remaining theoretically coherent and directly observable by the reader
  • Unique niche (meta-skill): serves as the repository's writing standard layer; the author claims every skill in the repo is authored according to it
  • Transparent disclosure of boundaries in documentation: explicitly states no automated eval exists and checks rely on manual runs, avoiding exaggerated capabilities
    • Best for: Individual authors and teams seeking to systematically improve the quality of 'agent-facing documents': maintainers of AGENTS.md/CLAUDE.md or skill repositories, agent skill authors, and reviewers auditing whether long documents are bloated (review passes represent a high-value use case). Ideal as a pre-authoring ruler and a post-authoring diagnostic vocabulary.
    Not for: Users needing out-of-the-box templates or checklist-style writing assistants; automated generators seeking 'let the agent write for me' (the docs explicitly note models produce verbose text by default, requiring humans to apply this reference to drafts); teams requiring machine-checked metrics or CI verification (author notes absence of automated evals); pure human-facing documentation unconsumed by any agent (would result in 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
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.