# Docs

> 参照文書（README・SKILL.md・API 文書・Markdown 全般）を美の基準で走査し，最も美しい確定版へ仕上げる．「READMEを完璧にして」「ドキュメントを美しくして」など，文書の仕上げを求められたときに使う（単発の小修正には使わない）．

- Skill: `tomoking2004/docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tomoking2004/docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomoking2004/docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomoking2004 (https://skillmd.com/u/tomoking2004)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/tomoking2004/docs

---


対象：指定された範囲の文書；無指定ならプロジェクト全文書（生成物のみ除く；`.gitignore` 対象も走査し，私的なメモ等は変更前に問う）．

まず [BEAUTY.md](../../BEAUTY.md) を読み，美の6条と走査の規律に従う．

## 媒体の正典

- **Markdown**：表題は一つ（H1 か frontmatter）；見出し階層は飛ばさない；列挙は文型・粒度を揃える．
- **README**：何であるか→なぜ→導入→使い方→開発の順．
- **SKILL.md**：description に機能と発動条件を最小トークンで（全セッションに常駐する）；本文は手順と判断規則のみ（一般知識は書かない）．
  - **節の順序**：「対象：」の一行 → 動的コンテキスト（あれば）→ 手順 → 判断規則（媒体の正典・文面の基準等）→ 網 → 制約 → 失敗時（/heal:skill を呼ぶ）．手順を持たない走査スキルは判断規則から始める；制約は手順に収まらない禁止・例外があるときだけ置く．
  - **網は必ず持つ**：確定前に当てる検査であり，当たる先で名が決まる——成果物に当てるなら**固有の走査**，成果物を残さず自分の段取りに当てるなら**自己点検**．網が手順と一体なら手順の中で走査を明示し，別節に写さない（単一の真実）．
  - **倣えと命じるなら手本を見せる**：「既存の声・様式に倣う」類の規則は，倣う対象を動的コンテキストで**実物のまま**出し（件名・要約・統計では声は伝わらない），網に「手本と**並べて**確かめる」項を置く．見せずに倣えとだけ書けば，読み手は想像で補う——規則を持ちながら守れない状態になる．及ぶのは**手本が固定のコマンドで取り出せるとき**に限る（`git log`・`gh release view` 等）——「既存ファイルの多数派に倣う」のように倣う対象が実行時の範囲で初めて決まるものは動的コンテキストに置けないので，代わりに**どこを見れば手本があるか**を規則自身が名指しする．
  - **倣う対象が選択なら条件と対で見せる**：倣わせたいものが**条件に応じた選び方**（変更の種類に対する type，ノートに載せる項目の取捨等）なら，選んだ**結果**だけを並べても倣えない——読み手は結果の語彙に自分の選択が入っていることを確かめ，「一致した」と判定して網を通してしまう（開発ツールに `chore` を当てるリポジトリで，語彙に `feat` があるからと新機能扱いする類）．**条件と結果の対**を出すこと——`git log --format='%h %s' --name-only` のように「何を変えた回がどれを選んだか」が見える形にする．対を固定のコマンドで出せないなら，倣えとは命じず**規則そのものを書き下ろす**．
  - **動的コンテキスト**：起こり得る全状態（非 git・初コミット前・タグ無し・**タグが HEAD**・作業ツリーが清潔等）で実行して裏取りし，**exit 0 かつ非空の出力**を保証する．非ゼロ終了は実行エラーになる．出力が空でも exit 0 は起こるため `cmd || echo "（なし）"` では足りない——`git log "$tag..HEAD"` はタグが HEAD にあるとき成功しつつ何も返さず，代替文が発火しない．空節は「該当なし」と「取得に失敗」を区別できないので，`x=$(cmd); [ -n "$x" ] && echo "$x" || echo "（なし）"` の形で必ず何かを出す．
- **その他**：その媒体の公式スタイルガイド；無ければ既存ファイルの多数派．

## 固有の走査

- **参照整合**：リンク・相互参照・目次が実在の対象を指すことを全件確かめる．
- **用語統一**：同義語群・表記の規約を全文書横断で列挙し，揺れを潰す．

## 制約

git は読み込みのみ．判断の割れる箇所は推測せず問う．

## 失敗時

/heal:skill を呼ぶ．