1仕組みと動作原理
実行スクリプト、ツール呼び出し、ネットワークリクエストを一切含まない純粋な「リファレンスドキュメント」型 skill。すべての機能は「エージェントのコンテキストに読み込まれ、その執筆行動を変化させる」ことによって実現され、執筆者（人間またはエージェント）に対する実行器ではなく「物差し」として機能する。
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）のみが存在し、コードが一切ないことが確認されている。『エージェント向けドキュメントを予測可能にする』という主張は、読者（エージェント）がその執筆原則を内面化することに依存しており、自動化によるものではない。
トリガー機構はモデルによる自動呼び出し（model-invoked）：frontmatter に description を保持し disable-model-invocation を設定しないことで、description がスキルの最上位 context pointer として機能し、その文言がエージェントによる資料読み込みのタイミングを決定する。
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 の仕組みは『disable-model-invocation を省略し、モデル向けの description を記述する』ことであり、本スキルの frontmatter もまさにその通りに作られており、自らの理論を実践している。description は 2 つのトリガー分岐（skill の作成、AGENTS.md/CLAUDE.md の変更）のみを記載しているが、本文の範囲ははるかに広い。自身の pointer 経済学に従い、常駐する description の各単語が context load を消費するため、最も価値の高い分岐のみを残している。
段階的開示（progressive disclosure）構造を採用：スキル特有の内容（frontmatter、呼び出し方式の選択、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.
自身が教える内容のドッグフーディング：SKILL-MECHANICS.md の冒頭文は自身を『The skill-specific branch of writing-for-agents』と称しており、これは情報階層における第 3 レベル『disclosed reference（開示されたリファレンス）』に相当する（メインファイル外に配置され、pointer によりオンデマンドでトリガーされる）。
行動のコアアンカーは『leading word』：モデルの事前学習にすでに存在する概念語（_lesson_、_fog of war_、_tracer bullets_）を意図的に単一トークンの行動アンカーとして採用。文を繰り返すのではなくトークンを繰り返すことで、最小限のトークン数でモデルの事前知識を喚起し、特定の行動領域を固定する。
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_）、ポジティブな目標行動のみをプロンプトすることを推奨している。
プルーニング（刈り込み）基準は文章の美しさではなく行動主義的な no-op テスト：モデルがデフォルトで従う指示は、負荷を払っただけで何も生み出さない no-op であり、削除時は文ごと削除すべきである。2 つの文の対立は、議論ではなく『ドキュメントを実行してみて挙動が変わるかどうか』で判定する。
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 などの失敗パターンの用語も提示されており、本スキルの用途の半分は、これらの語彙を診断ツールとして用いた既存ドキュメントのレビューにある。
『2 つの負荷』（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』のメカニズムによって、エージェントが時期尚早な完了（premature completion）に陥る理由とその防御策を解説している。
2コア機能
01エージェントが消費するあらゆるドキュメント（skill、AGENTS.md/CLAUDE.md、pointer が指すドキュメント）の執筆・レビュー
02context pointer の文言とトリガー分岐の設計（フロントロード、1 分岐 1 トリガー、本文に含まれる識別子の削ぎ落とし）
03情報階層を用いたコンテンツ帰属層の決定、段階的開示（progressive disclosure）と同見出しへの集約（co-location）の実施
04premature completion を防ぐ completion criteria（clarity/demand）の設計、legwork（下調べ作業）の強度管理
05ドキュメント分割タイミングの判断：順序に応じた分割（後続ステップの隠蔽）と invocation に応じた分割
06トークンを圧縮し行動を固定するための leading word の抽出、negation アンチパターンの回避
07文単位のプルーニング：single source of truth、関連性、no-op テスト、duplication/sediment/sprawl の排除
08（サブスキル、SKILL-MECHANICS）model-invoked と user-invoked の選定、記憶の負担を集約する router skill の設計
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
自動ロード可能
管理者向け
ソースとバージョンの記録
判定根拠（ファイルパスと抜粋）
- SKILL.md: スクリプト実行や外部への影響を持たない、純粋なプロンプト指示およびルールテキスト
監査ノート： ディレクトリ全体で 3 つの静的テキストファイル（SKILL.md / SKILL-MECHANICS.md / agents/openai.yaml）のみで構成され、git ls-tree によりスクリプト、バイナリ、隠しファイル、シンボリックリンクが存在しないことが確認されている。3 ファイル全体に対する http/curl/exec/$( の grep 検索でもヒットはゼロであり、ネットワーク呼び出し、認証情報の読み込み、ファイル書き出しは一切ない。純粋な助言的リファレンスであり実行面が存在しないため、リスクは利用シナリオにのみ起因する。
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結論
最適な用途： 「エージェント向けドキュメント」の品質を体系的に向上させたい個人の執筆者やチーム：AGENTS.md/CLAUDE.md またはスキルリポジトリを保守する担当者、エージェントスキルの開発者、既存の長文ドキュメントが肥大化していないかレビューする必要がある人（レビュー工程は本スキルの高価値なユースケース）。執筆前の物差しとして、また執筆後の診断用ボキャブラリーとしての利用に適している。
不向きな用途： すぐに使えるテンプレートやチェックリスト形式のライティングアシスタントを求める人、「エージェントに代わりに書いてほしい」と考える自動生成志向の人（ドキュメント内では、モデルがデフォルトで冗長なテキストを出力するため人間がドラフトに本リファレンスを適用する必要があると明言されている）、機械的に検証可能な指標や CI による検証を必要とするチーム（作者自身が自動 eval はないと述べている）、エージェントを介さず人間のみが閲覧する純粋なドキュメント（オーバーエンジニアリングになる）。
Install Agent-Ready
① Verified Mirror 2026-09-06
Option A · Direct DownloadDownload writing-for-agents.tar.gz
sha256:
Option B · Copy Guide for Agent2741c227a60b8035…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 3cca18b368.