documentation-engineer

documentation-engineer スキルの概要

documentation-engineer スキルは何のためのものか

documentation-engineer スキルは、粗いプロダクト情報、API情報、コードの文脈を、構造化された技術ドキュメントに落とし込むためのドキュメント特化ワークフローです。ゼロから書くよりも速く、しかも整理しやすく保守しやすい形で、README、APIリファレンス、コードコメント、アーキテクチャ文書を整えたいチームに向いています。

向いているユーザー・チーム

この documentation-engineer スキルが特に合うのは、次のようなケースです。

• すでに理解している repo をドキュメント化したい開発者
• 手元のソース情報から一次稿を起こしたいテクニカルライター
• README や API ドキュメントの構成を標準化したいエンジニアリングチーム
• 文章生成だけでなく、テンプレートや検証支援もほしいメンテナー

不完全な入力しかない状態で、短い納期の中で Technical Writing を進めるなら、このスキルは単なる汎用的な “write docs” プロンプトより実用的です。テンプレート、スタイルガイド、補助スクリプトが最初から揃っているためです。

実際にどんな仕事を前に進められるか

多くのユーザーが必要としているのは「文章量」ではなく、次の問いに答えられる使えるドキュメントです。

• このプロジェクトは何をするものか
• どうインストールし、どう実行するか
• API やツールをどう使うか
• どの設定が重要か
• 読み手が最初にどこでつまずくか

documentation-engineer スキルが最も力を発揮するのは、すでにコード、エンドポイント、コマンド、設計情報があり、それを読み手向けドキュメントへ、予測しやすいセクション構成で変換したい場面です。

通常のプロンプトと何が違うのか

違いは魔法のようなものではなく、実務上の差にあります。

• README、API docs、コメント、アーキテクチャ文書を対象にした、明文化されたトリガー範囲
• references/readme-template.md、references/api-template.md、references/style-guide.md にある再利用可能な参照資料
• スキャフォールド生成と基本的なセクション検証を行う 2 つの補助スクリプト
• 自由形式のマーケティング文よりも、ドキュメント構造、実例、保守性を優先する設計

インストール前に知っておきたいこと

これはフル機能の docs site generator でも、言語特化の API extractor でもありません。リポジトリを見る限り、実体はテンプレートと軽量な Python スクリプトであり、深い repo 解析や自動的な schema 発見までは行いません。構造とガードレールを備えた実務的なドキュメント支援がほしいなら documentation-engineer を入れる価値があります。一方で、docs build system、OpenAPI publishing pipeline、static-site framework 連携が必要なら見送るほうが適切です。

documentation-engineer スキルの使い方

documentation-engineer のインストール前提

リポジトリの SKILL.md には、このスキル単体のインストールコマンドは書かれていないため、通常は親コレクションから追加します。

npx skills add zhaono1/agent-playbook --skill documentation-engineer

インストール後は、次の skill ディレクトリを起点に確認すると進めやすいです。

• skills/documentation-engineer/SKILL.md
• skills/documentation-engineer/README.md
• skills/documentation-engineer/references/
• skills/documentation-engineer/scripts/

最初に読むべきファイル

最短で使い始めるなら、読む順番は次のとおりです。

1. SKILL.md で発動範囲と対象ドキュメント種別を確認
2. README.md で想定ユースケースとスクリプトの入口を把握
3. repo やプロダクト向け docs が必要なら references/readme-template.md
4. エンドポイントや関数の docs が必要なら references/api-template.md
5. 見出し、リンク、コードブロックを整えるなら references/style-guide.md

この順で見れば、repo 全体を流し読みするより早くワークフローをつかめます。

うまく機能させるために必要な入力

documentation-engineer スキルは、目的だけでなくソース材料が渡されたときに最も良い結果を出します。特に有効なのは次のような入力です。

• リポジトリ構成
• install / run の主要コマンド
• 設定変数
• API ルートや関数シグネチャ
• 想定ユーザーペルソナ
• よくある失敗パターン
• 古くなっている既存 docs

弱い入力: “Document this project.”

強い入力: “Create a README for a Python CLI that syncs S3 files, supports sync and plan, uses AWS credentials from env vars, and is run with python -m syncer.”

ざっくりした依頼を良いプロンプトに変える

良い documentation-engineer usage プロンプトでは、少なくとも次を明示すると精度が上がります。

• ドキュメント種別
• 想定読者
• ソースとなる成果物
• 必須セクション
• 出力形式
• 制約条件

例:

“Use the documentation-engineer skill to draft a README for this internal Go service. Audience is new backend engineers. Include Overview, Quick Start, Configuration, API summary, Troubleshooting, and Ownership. Base it on cmd/, internal/config/, .env.example, and the existing Makefile. Keep examples runnable and flag unknowns explicitly.”

このプロンプトが優れているのは、読み手、範囲、根拠、構成がすべて定義されているからです。

内蔵テンプレートは意図を持って使う

参照ファイルはシンプルですが、判断の助けとして十分役立ちます。

• references/readme-template.md はセットアップや開発向けセクションの抜け漏れを防ぐ
• references/api-template.md はパラメータ、レスポンス、エラー、実例を入れるよう促す
• references/style-guide.md は読みやすさとコード例の質を底上げする

単なる穴埋め用フォーマットとして扱わず、その repo の実際のワークフローに合わせて調整してください。

Technical Writing 向けのおすすめ手順

documentation-engineer for Technical Writing を使うなら、次の流れが安定します。

1. repo と実行コマンドを確認する
2. 足りない事実をコードやメンテナーから集める
3. まず 1 種類のドキュメントに絞る。通常は README から始める
4. 最も近い reference template を使って下書きを作る
5. 実際のコマンドや payload から例を追加する
6. セクションの網羅性を検証する
7. わかりやすさと作業順に沿って書き直す

最初から全部の docs を一気に生成しようとするより、このやり方のほうがうまくいきます。

補助スクリプトでスキャフォールドを生成する

素早く叩き台を作りたいなら、次を使えます。

python scripts/generate_docs.py --output docs/README.md --name "Your Product" --owner "Your Team"

便利なフラグ:

• --output 出力先を指定
• --name プロダクト名またはサービス名を埋め込む
• --owner オーナー情報を明示する
• --force 既存ファイルを上書きする

このスクリプトは基本的なものですが、真っ白な状態から書き始める負担を減らし、予測しやすい docs の骨組みを作れます。

公開前に docs を検証する

主要セクションの欠落を検出するには validator を使います。

python scripts/validate_docs.py --input docs/README.md

デフォルトの必須見出しには次が含まれます。

• ## Overview
• ## Ownership
• ## Quickstart
• ## Configuration
• ## Usage
• ## Troubleshooting

追加も可能です。

python scripts/validate_docs.py --input docs/README.md --require "## API Reference"

複数人で docs を触る運用では、セクション構成が少しずつ崩れやすいため、特に有効です。

出力品質を最も左右するもの

品質を一番大きく左右するのは、具体的な運用情報を渡せているかどうかです。このスキルは構成を整えるのは得意ですが、次のような事実を勝手に捏造することはできません。

• 正確な install コマンド
• 実在する environment variables
• 正しい error conditions
• 安定して使える examples
• チームの ownership 情報

これらが欠けると、見た目は整っていても中身の浅い結果になりがちです。

価値が出やすい代表的なユースケース

documentation-engineer skill の実用面で特に効果が高いのは、次のような場面です。

• docs が不足している repo に、最初のまともな README を作る
• サービス横断で API endpoint docs の書き方を標準化する
• 自明な挙動ではなく意図に焦点を当てて inline comments を改善する
• 社内システム向けに architecture docs や ownership docs の草案を作る
• 属人的な知識を、明確なセクションを持つ保守可能な docs に変える

このスキルがあまり向かないケース

次のような要件が主なら、documentation-engineer usage を中核の解決策にするのは避けたほうがよいです。

• 大規模 codebase から高精度に自動抽出したい
• schema だけから API docs を生成したい
• Docusaurus、MkDocs、Sphinx 向けの publishing workflow が必要
• docs localization pipeline を組みたい
• 厳格なレビューゲートを持つ compliance documentation が必要

これは強力な下書き・構造化支援ですが、フル機能の documentation platform ではありません。

documentation-engineer スキル FAQ

documentation-engineer は普通のプロンプトより良い？

多くの場合は Yes です。特に課題が「文章力」より「構成」と「抜け漏れ防止」にあるなら有利です。documentation-engineer スキルには、より明確な docs の型、再利用できるテンプレート、validator による支援があります。通常のプロンプトでもそれなりの文章は出せますが、configuration、troubleshooting、ownership のような重要セクションを落としやすくなります。

documentation-engineer スキルは初心者にも使いやすい？

はい。特に、たまにドキュメントを書く開発者には扱いやすい部類です。repo は軽量で、references は読みやすく、scripts もシンプルな Python utility です。複雑なセットアップがなくても価値を得られます。

このスキルを使うのに Python は必要？

考え方として documentation-engineer を使うだけなら Python なしでも可能です。ただし、スキャフォールド生成と検証のワークフローを使いたい場合は、補助スクリプト（generate_docs.py と validate_docs.py）の実行に Python が必要です。

コードから API docs を自動生成できる？

深い意味での自動生成はできません。リポジトリの実態を見ると、あるのは API docs 用テンプレートであって、パーサーベースの完全自動抽出ではありません。ルート、パラメータ、レスポンス、エラー条件は自分で渡すか、提供したコードからモデルに推定させる必要があります。

社内向け docs にも documentation-engineer は使える？

はい。むしろ社内サービス向け docs と相性が良いです。スキャフォールドに ownership、quickstart、configuration、troubleshooting といった、社内読者が特に必要としやすいセクションが含まれているためです。

どんなときに documentation-engineer を入れないほうがいい？

主に次のものを求めているなら、documentation-engineer の導入は見送ったほうがよいです。

• docs website framework
• schema-driven reference generation
• 強く自動化された code-to-doc pipeline
• 1 つの言語エコシステム専用に最適化された style system

入れるべきなのは、軽いガードレール付きで再利用可能な docs 下書きワークフローがほしいときです。

documentation-engineer スキルを改善するには

抽象論ではなく根拠を渡す

documentation-engineer の出力を改善したいなら、大まかな意図ではなく repo の事実を渡してください。たとえば次のような情報です。

• package.json、pyproject.toml、Makefile、または Docker コマンド
• .env.example や config structs
• route definitions や SDK signatures
• sample requests と responses
• 既知のセットアップ上の落とし穴

これにより、無難な埋め草が減り、install 手順の正確さも上がります。

一度に 1 種類のドキュメントを依頼する

よくある失敗は、スコープが広すぎることです。“write all docs for this project” は避けたほうがよいです。よりよい進め方は次のとおりです。

• まず README
• 次に API reference
• その次に troubleshooting
• 必要に応じて code comments

対象を小さく区切るほど、精度が高く保守しやすい docs になりやすくなります。

読み手と成功条件を明示する

強いプロンプトは、その docs が誰向けで、何をもって成功とするかを明確にします。

例:
“Use the documentation-engineer skill to write a Quick Start for new contributors who have never run this service locally. Success means they can install dependencies, configure env vars, start the app, and verify health in under 10 minutes.”

この指示があるだけで、セクション順、用語選び、例の出し方が変わります。

Usage セクションを良くするには実例を渡す

Usage セクションの質は、次のような具体例を渡すと大きく上がります。

• 正確な CLI invocation
• curl examples
• JSON payloads
• expected output snippets
• ユーザーが実際に目にする error messages

また、style guide ではコードブロックを最小限かつ実行可能に保つよう促しているので、レビュー時にもそこは意識して守る価値があります。

validator と二段階レビューで docs を締める

改善ループとしては、次の流れが効果的です。

1. draft を生成する
2. 最も近い reference template と照合する
3. scripts/validate_docs.py を実行する
4. 欠けているセクションを補う
5. わかりにくい手順を作業順に書き直す
6. repo に裏付けのない記述を削る

シンプルですが、docs の弱点のかなりの部分をこの流れで拾えます。

よくある失敗パターンを重点的に直す

documentation-engineer guide のワークフローでは、特に次の点をチェックしてください。

• ユーザーの得られる結果が見えない、汎用的すぎる概要文
• 前提条件が抜けた install 手順
• エラーやレスポンス例のない API docs
• デフォルト値や目的が書かれていない設定項目一覧
• コードの内容を言い換えるだけで、存在理由を説明していないコメント

このあたりは、狙って修正すると最も効果が出やすい箇所です。

references はレビュー用チェックリストとしても使う

reference ファイルは下書き用だけではありません。レビュー用チェックリストとしても使えます。

• readme-template.md は網羅性チェックに
• api-template.md は endpoint coverage の確認に
• style-guide.md は読みやすさと書式の一貫性の確認に

基盤 repo を変えずに documentation-engineer skill の品質を上げる方法として、これは最も手軽なもののひとつです。

自分たちの docs システムに合わせてスキャフォールドを調整する

チームで docs を docs/、wiki pages、あるいは monorepo の service folders に置いているなら、generator の出力先や必須見出しをその運用に合わせて変更してください。scripts は意図的に軽量なので、必要なら既存の CI、pre-commit、review workflow に組み込みやすく、より強い運用ルールにも発展させやすいです。