agentleFS
Sign inStart free
kompirokompiro/hane/skills/review-docs/SKILL.md

review-docs

Skill0 starsChanged 6 months agoMITView on GitHub

Review documentation for broken links and cross-document consistency issues. Trigger when the user says: "ドキュメントレビュー", "docs review", "review docs", "リンク切れ確認", "ドキュメントの整合性", or similar phrases requesting documentation review.

23 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-vercel-ai-issue, dev-auth-bypass and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • FranciscoMorettiSkill

    create-vercel-ai-issue

    Create a well-formed GitHub issue in vercel/ai using the gh CLI. Use when reporting an AI SDK bug or preparing an issue body that contains logs, code blocks, versions, reproduction steps, and shell-sensitive text.

    Also in 3 projects that use this

  • FranciscoMorettiSkill

    dev-auth-bypass

    Authenticate a browser against a local ChatJS app without OAuth. Use for development login, local auth bypass, authenticated browser or Playwright testing, and the /api/dev-login route.

    Also in 3 projects that use this

  • +10 more from FranciscoMoretti

The file

Create a free account to mount
Files
SKILL.md

Review Docs Skill

docs/ 以下のドキュメント全体を走査し、リンク切れと整合性問題を検出してレポートを出力する。

アーキテクチャ

このスキルは処理を2つのサブエージェントに分担させることでメインのコンテキストを節約する。

/review-docs（メインエージェント）
├── Explore エージェント A: リンク切れチェック（並列起動）
├── Explore エージェント B: 整合性チェック（並列起動）
└── メインエージェント: 両結果を受け取りレポート生成

手順

1. サブエージェントを並列起動する

以下の2つの Explore エージェントを 同時に（1メッセージで） 起動する。

サブエージェント A — リンク切れチェック

プロンプト（要旨）:

docs/**/*.md および CLAUDE.md 全件を読み込み、各ファイルに含まれる Markdown リンク [text](path) と画像参照 ![alt](path) を抽出せよ。

チェック対象:

  • 相対パス参照 → リポジトリルートから解決して実ファイルの存在確認
  • アンカー付きリンク [text](file.md#anchor) → 対象ファイルに該当見出し（# ..., ## ... 等）が存在するか確認
  • / 始まりの絶対パス → リポジトリルートから存在確認

チェック対象外:

  • http://, https:// で始まる外部リンク

結果は以下の形式で返せ:

BROKEN_LINK|ファイルパス|行番号|リンク記述|理由
BROKEN_LINK|docs/requirements.md|125|[コアコンセプト](design/concepts.md)|ファイルが存在しない
OK_LINK_COUNT|32
TOTAL_FILES|18

サブエージェント B — 整合性チェック

プロンプト（要旨）:

docs/ 以下のすべての Markdown ファイルを読み込み、以下の観点で整合性を確認せよ。 各観点は対応するディレクトリ・ドキュメントが存在する場合のみ実行し、無ければスキップする。

1. CLAUDE.md ドキュメント表 CLAUDE.md 内に「ドキュメント」表（または同等のパス一覧）が存在する場合、記載されたファイルパスが実在するか確認する。

2. ADR ↔ Design Doc の対応（docs/adr/ がある場合のみ）

  • ADR に「関連」として記載された Design Doc のパスが実在するか
  • Design Doc のステータスが「ADR化」の場合、対応する ADR ファイルが存在するか

3. Design Doc のステータスと実装状態の乖離（docs/design/ がある場合のみ）

  • ステータスが「完了」の Design Doc に対応する ADR が存在しないもの（警告）
  • ステータスが「ドラフト」「検討中」のまま実装されていそうなもの（git history は見なくてよい、判断できる範囲で）

4. Design Doc ↔ AT の対応（docs/design/ と docs/acceptance/ の両方がある場合のみ）

  • 各 Design Doc に対応する AT（docs/acceptance/）が存在するか（なければ警告のみ）

5. AT 番号の重複（docs/acceptance/ がある場合のみ）

  • docs/acceptance/<番号>-*.md の番号プレフィックスが重複しているものがないか
  • 採番は Issue 番号 → PR 番号 → ローカル採番（既存最大+1）の優先順位。同一 Issue / 同一 PR に複数 AT（例: 42-login-form.md, 42-login-error.md）は許容されるため WARN にしない
  • 異なる採番ソース同士の衝突（例: Issue #5 と ローカル採番 5- の併存）のみ WARN として報告する（ERROR にしない）

6. AT に記載された実装ファイルの存在確認（docs/acceptance/ がある場合のみ）

  • AT の bash コードブロック内に登場するソースパス（プロジェクト内の相対パス）のファイルが実在するか

結果は以下の形式で返せ:

ERROR|カテゴリ|説明
WARN|カテゴリ|説明
OK|カテゴリ|説明
TOTAL_FILES|N

例:

ERROR|AT番号重複|docs/acceptance/0007-qa-skill.md と docs/acceptance/0007-deployment-diagram.md が同じ番号
WARN|Design Doc ステータス|docs/design/deployment-diagram.md: ステータス「完了」だが対応する ADR が存在しない
OK|CLAUDE.md ドキュメント表|全エントリ実在

2. 両エージェントの結果を受け取る

サブエージェント A・B それぞれの出力を解析し、以下に整理する:

  • リンク切れ一覧（ファイル・行番号・内容・理由）
  • 整合性エラー一覧（ERROR 行）
  • 整合性警告一覧（WARN 行）
  • 問題なしカテゴリ一覧（OK 行）

3. レポートの生成

以下の形式で docs/review/YYYY-MM-DD-review.md を生成する（今日の日付を使用）。 docs/review/ ディレクトリが存在しない場合は作成する。

# Docs Review — YYYY-MM-DD

## Summary

- Broken links: N (errors)
- Consistency issues: N (errors), N (warnings)
- Total documents reviewed: N

---

## Broken Links

### docs/requirements.md

- Line 125: `[コアコンセプト](design/concepts.md)` → ファイルが存在しない

---

## Consistency Issues (Errors)

### AT 番号重複

...

---

## Consistency Issues (Warnings)

### Design Doc ステータスと ADR の不整合

...

---

## No Issues Found

（問題がなかったカテゴリはここに列挙）

---
*Generated by /review-docs skill — do not commit this file*

4. 結果の報告

生成したファイルのパスをユーザーに伝える。 検出した問題件数をカテゴリ別にサマリーとして表示する。 問題がゼロの場合は「問題なし」と明記する。

出力先

  • docs/review/YYYY-MM-DD-review.md（git には追加しない、.gitignore 対象）

注意事項

  • サブエージェントは必ず 同時に（単一メッセージで） 起動して並列処理を活かす
  • 外部 URL（https:// 等）の到達性チェックは行わない（CI 環境依存を避けるため）
  • 同じ問題が複数箇所で検出される場合は重複せず、最初の出現箇所のみ記録する
  • ファイルパスはリポジトリルートからの相対パスで表記する
  • 警告（望ましいが必須ではない）とエラー（明確な問題）を区別して表記する
    • エラー: リンク切れ、存在しないファイル参照
    • 警告: 対応 AT がない Design Doc、ステータス乖離など
  • AT 番号は GitHub Issue 番号 → PR 番号 → ローカル採番の優先順位で付与する。外部参照を保つため再採番（リネーム）は提案しない。異なる採番ソース同士の衝突のみ WARN として報告する

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free