SBTopZZZ-LG/documentation-workspace-skill

このファイルはスキル利用者向けであり、コントリビューター向けではありません。開発コンテキスト（このスキルの構築、反復、テスト方法）については AGENTS.md を参照してください。

ドキュメントワークスペース ブートストラップ

このスキルは、AIエージェントに空（またはほぼ空）のディレクトリにドキュメントワークスペースをゼロから構築する方法を教えます。結果として得られるのは、バージョン管理され、ファイルシステムベースで、完全に自己完結した知識ベースです。ユーザーが所有し、無料で、ベンダーロックインがなく、そこで作業するエージェントが組織化、フォーマット、ツールについて考える必要がないように構造化されています。

核となるアイデア

ブートストラップされたワークスペースには、独自のAGENTS.mdが含まれています。これはワークスペースごとの、トピック固有の「凍結されたミニスキル」であり、エージェントはエントリ時に読み込みます。AGENTS.mdは、このスキルが提供するテンプレートから作成されます。ワークスペースが存在するようになったら、エージェントはこのスキルではなくAGENTS.mdに従います。これがすべての要点です：ルールを一度事前決定し、その後それらを再導出するためにトークンを焼き尽くすことはありません。

このスキルを使用するタイミング

このスキルは以下の場合のみ使用してください：

• ユーザーが明示的にドキュメントワークスペース、ドキュメントフォルダ、またはナレッジベースを作成/セットアップ/初期化/スキャフォールディングしたい場合。
• ターゲットディレクトリが空またはほぼ空である場合（またはユーザーが既存ファイルにもかかわらず明示的にオプトインした場合）。
• ターゲットディレクトリに既にAGENTS.mdが存在しない場合（存在する場合は、既にブートストラップ済みです）。

ターゲットにAGENTS.mdが既に存在する場合：このスキルを実行しないでください。 既存のAGENTS.mdを読み、それに従ってください。ユーザーは既にブートストラップされたワークスペースにいます。

このスキルを使用してはいけないタイミング

• ユーザーが既存のワークスペース内でドキュメントの追加、編集、リンク、再編成をしたい場合 — その場合はワークスペース自身のAGENTS.mdが統治します。
• ユーザーがGitHubにプッシュしたり、ブラウザでワークスペースをレンダリングしたり、ホスティングをセットアップしたい場合 — これらは別の関心事であり、別のスキルが必要です。
• ユーザーが文書作成、ライティング、ノートテイキングに関する一般的な質問をしている場合 — スキルは不要です。

スキルが生成するもの

呼び出されると、このスキルは以下のファイルを含むワークスペースを作成します：

ファイル/ディレクトリ	目的
AGENTS.md	ワークスペースごとの「凍結されたミニスキル」。95%がルール、5%がトピック要約。エージェントはエントリ時にこれを読みます。
README.md	ワークスペースレベルの概要。よりリッチなイントロ、自動生成インデックス、AGENTS.mdへのポインタ。
index.yaml	ルートディレクトリのドキュメント順序。デフォルトでは空。
.gitignore	適切なデフォルト: バックアップ、OSジャンク、エディタファイル、Node。
package.json	開発依存関係: prettier、markdownlint-cli、js-yaml。ツール用のnpmスクリプト。
.prettierrc	Prettier設定: 120文字行、proseWrap preserve。
.markdownlint.json	ニットピックルールを無効にしたmarkdownlint設定。
scripts/	ヘルパースクリプト: format.js、validate.js、hash.js、reindex.js。
assets/	空の共有アセットディレクトリ。ワークスペースルートに作成されます。

gitが利用可能な場合、Gitリポジトリがワークスペース内に初期化されます。Nodeとnpmが利用可能な場合、開発依存関係がインストールされます。

ブートストラップワークフロー

以下の手順を順番に実行してください。指示のある各ステップでユーザーに確認してください。 決して推測しないでください。

ステップ1 — ターゲット位置の確認

ユーザーに尋ねます：「ドキュメントワークスペースを <cwd> にブートストラップします。これでよろしいですか？（はい / いいえ / パスを指定）」

• はいの場合：カレントディレクトリをターゲットとして続行します。
• いいえの場合：正しいパスを尋ね、確認してから続行します。
• ユーザーが「このフォルダに」などと言った場合：カレントディレクトリと見なしますが、それでも確認してください。

ステップ2 — ターゲットが空であることの確認（またはオプトインの取得）

ターゲットディレクトリの内容を一覧表示します（.gitなどの隠しファイルは除く）。

空の場合：ステップ3に進みます。

空でない場合：

1. ユーザーにそこにあるものを表示します。
2. 説明します：「このディレクトリは空ではありません。デフォルトでは、このスキルは空でないディレクトリへのブートストラップを拒否します。以下のオプションがあります：(a) 中止する、(b) 続行することを確認していただき、既存ファイルには触れない、(c) ワークスペースを作成するサブディレクトリを指定する。」
3. 明示的な確認を待ちます。ユーザーが明確な肯定的な肯定をしない場合、中止します。
4. ユーザーが「続けて」または「はい、進めて」と言った場合 — それをオプトインとして記録し、続行します。

ターゲットにAGENTS.mdが既に存在する場合：停止します。 ワークスペースは既にブートストラップされています。ユーザーに伝え、既存のAGENTS.mdを読むことを提案します。

ターゲットでgitが既に初期化されている場合：後のgit initステップをスキップしますが、続行します。

ステップ3 — トピック要約の収集

ユーザーに尋ねます：「このドキュメントワークスペースは何のためのものですか？トピックを1〜2短い段落で説明してください。これはAGENTS.mdのトピック要約とREADME.mdのイントロになります。」

トピック要約のルール：

• 1段落（推奨）、最大2段落
• プレーンな散文、フォーマットなし、リストなし
• ワークスペースが何を文書化するかを明確に示す

ユーザーが1文だけを提供した場合：それで問題なく使用します。 ユーザーがより長い説明を提供した場合：短縮するか（確認を得て）、最大2段落で使用します。 ユーザーが「あなたが決めて」や「まだわからない」と言った場合：少なくとも1文を促します。トピック要約はAGENTS.mdの唯一のトピック固有部分であり、ワークスペースには何らかのアンカーが必要です。

ステップ4 — ブートストラップスクリプトの実行

以下を入手したら：

• ターゲットパス
• ディレクトリが適切であることの確認
• トピック要約

...ブートストラップスクリプトを実行します：

---

node /assets/skill-scripts/bootstrap.js --target --topic ""

スクリプトは以下を行います：

1. Node.jsの可用性を確認（利用不可の場合はNode依存アーティファクトをスキップし警告）
2. gitの可用性を確認（利用不可の場合はgit initをスキップ）
3. ディレクトリ構造を作成
4. <skill-dir>/assets/templates/ からすべてのテンプレートを {{TOPIC_SUMMARY}} と {{CREATED}} を置換してインスタンス化
5. ワークスペースに同梱するスクリプト（format.js、validate.js、hash.js、reindex.js）を <target>/scripts/ にコピー
6. npm install を実行（Node + npmが利用可能な場合）
7. git init を実行（gitが利用可能な場合）
8. 作成されたもののサマリーを出力

スクリプトが失敗した場合（例：権限、ツール不足）、<skill-dir>/assets/templates/ のテンプレートを使用して手動でファイル作成にフォールバックします。各テンプレートをターゲットに手動でコピーし、プレースホルダーを置換し、<skill-dir>/assets/workspace-scripts/ からコピーして scripts ディレクトリを作成します。

ステップ5 — 作成されたものをユーザーに伝える

スクリプトの終了後、以下を要約します：

• 作成されたファイルとディレクトリ
• git init が実行されたか（またはスキップされた場合、その旨のリマインダー）
• npm install が実行されたか（またはスキップされた場合、その旨のリマインダー）
• AGENTS.md がこのワークスペースの統治ドキュメントになったこと
• ワークスペースが使用可能になったこと

そして尋ねます：「ドキュメントの作成を始めますか、それともまず構造を確認しますか？」

テンプレート

すべてのテンプレートファイルは <skill-dir>/assets/templates/ にあります。ブートストラップスクリプトがこれらをコピーし、置換します。

テンプレート	生成物
AGENTS.md.template	AGENTS.md
README.md.template	README.md
index.yaml.template	index.yaml
_gitignore_.template	.gitignore（アンダースコアで囲まれたものはドットプレフィックスになります）
package.json.template	package.json
_prettierrc_.template	.prettierrc
_markdownlint.json_.template	.markdownlint.json

使用されるプレースホルダー：

• {{TOPIC_SUMMARY}} — ユーザーのトピック記述で置換
• {{CREATED}} — 今日の日付（YYYY-MM-DD）で置換

ブートストラップスクリプトはアンダースコアラッピングの慣習を自動的に処理します（_foo_.template という名前のファイルは出力で .foo になります）。

ワークスペースに同梱されるスクリプト

ブートストラップ後、ワークスペースには scripts/ に以下のヘルパースクリプトがあります：

スクリプト	目的
scripts/format.js	すべての .md/.html/.json/.yaml ファイルに対してPrettierを実行
scripts/validate.js	すべての .md ファイルに対してmarkdownlintを実行
scripts/hash.js	ファイルのSHA-256ハッシュを計算し、オプションで assets/ に書き込みマニフェストを更新
scripts/reindex.js	README.md の自動インデックスセクションを再生成

すべてnpmから呼び出し可能：

• npm run format
• npm run validate
• npm run hash
• npm run reindex

リファレンス

特定のトピックに関するより深いコンテキストについては、references/ ディレクトリを参照してください：

• references/asset-management.md — アセットの追加、リンク、移行方法（コンテンツアドレスストレージ、マニフェスト、ドキュメントごと vs 共有）
• references/document-promotion.md — 単一ファイルのドキュメントがサブドキュメントを獲得したときにフォルダに昇格する方法

これらは関連する場合にのみコンテキストに読み込まれます。メインのAGENTS.mdは一般的なケースをカバーし、リファレンスはあまり一般的でないケースのためのものです。

エージェントへのリマインダー（ブートストラップ中）

• トピック要約はユーザーが提供する唯一のトピック固有コンテンツです。その他はすべてテンプレート化されています。ファイル名、リンクスタイル、フロントマター項目、コミットメッセージスタイル、その他のルールについて尋ねないでください — これらはテンプレートに組み込まれています。
• ユーザーがテンプレートでサポートされていないものを要求した場合、それを表面化させてください。新しい慣習を黙って発明しないでください。正しい対応は、(a) 将来のテンプレート改訂のためにそれをメモする、または (b) 明示的な確認を得て例外として実装する、のいずれかです。
• ブートストラップ後、このスキルは終了です。 次にユーザーがワークスペース内で何かを行いたい場合、エージェントは AGENTS.md を読み、それに従います。このスキルは、ユーザーが明示的に別のワークスペースをブートストラップするか、既存のワークスペースを再ブートストラップするよう要求しない限り、再度実行されることはありません。