documentation-update

ドキュメント更新スキル

このスキルは、マーケットプレイスのカタログを読み込み、Jinja2 テンプレートを適用して、docs/ ディレクトリ内のドキュメントファイルを自動的に再生成します。

目的

以下を行って、ドキュメントの同期状態を維持します。

• エージェントのリファレンスドキュメントを生成する
• スキルカタログのドキュメントを作成する
• プラグインディレクトリを構築する
• 使用ガイドを更新する
• すべてのドキュメント間の一貫性を確保する

使用するタイミング

以下の場合にこのスキルを使用します。

• マーケットプレイスに新しいプラグインが追加された
• 既存のプラグインが更新された（コンポーネントが追加・削除された）
• エージェントまたはスキルのメタデータが変更された
• ドキュメントを再生成する必要がある
• ドキュメントをマーケットプレイスの状態に一致させる必要がある

ドキュメントファイル

このスキルは、次の 4 つの主要なドキュメントファイルを生成します。

1. agents.md

すべてのプラグインに含まれる、すべてのエージェントのリファレンスです。

• プラグインごとに整理されています
• エージェント名、説明、モデルを一覧表示します
• エージェントファイルへのリンクを含みます
• エージェントの機能とユースケースを示します

2. agent-skills.md

段階的開示の詳細を含む、すべてのスキルのカタログです。

• プラグインごとに整理されています
• スキル名と説明を一覧表示します
• 「使用するタイミング」のトリガーを示します
• スキルの構造に関する情報を含みます

3. plugins.md

マーケットプレイス内のすべてのプラグインのディレクトリです。

• カテゴリごとに整理されています
• プラグイン名、説明、バージョンを示します
• コンポーネント（エージェント、コマンド、スキル）を一覧表示します
• インストールおよび使用方法を提供します

4. usage.md

使用ガイドおよびコマンドリファレンスです。

• 始め方の手順
• コマンドの使用例
• ワークフローのパターン
• 統合ガイド

テンプレートの構造

テンプレートは、Jinja2 構文を使用して assets/ に保存されています。

assets/
├── agents.md.j2
├── agent-skills.md.j2
├── plugins.md.j2
└── usage.md.j2

テンプレート変数

すべてのテンプレートは、以下のコンテキストを受け取ります。

{
  "marketplace": {
    "name": "marketplace-name",
    "owner": {...},
    "metadata": {...},
    "plugins": [...]
  },
  "plugins_by_category": {
    "category-name": [plugin1, plugin2, ...]
  },
  "all_agents": [
    {
      "plugin": "plugin-name",
      "name": "agent-name",
      "file": "agent-file.md",
      "description": "...",
      "model": "..."
    }
  ],
  "all_skills": [
    {
      "plugin": "plugin-name",
      "name": "skill-name",
      "path": "skill-path",
      "description": "..."
    }
  ],
  "all_commands": [
    {
      "plugin": "plugin-name",
      "name": "command-name",
      "file": "command-file.md",
      "description": "..."
    }
  ],
  "stats": {
    "total_plugins": 10,
    "total_agents": 25,
    "total_commands": 15,
    "total_skills": 30
  }
}

Python スクリプト

このスキルには doc_generator.py という Python スクリプトが含まれており、以下を実行します。

1. marketplace.json を読み込む

   • マーケットプレイスのカタログを読み込む
   • 構造を検証する
   • コンポーネントのインデックスを構築する

2. プラグインファイルをスキャンする

   • エージェント／コマンドの frontmatter を読み込む
   • スキルのメタデータを抽出する
   • 包括的なコンポーネント一覧を構築する

3. テンプレートコンテキストを準備する

   • プラグインをカテゴリごとに整理する
   • コンポーネントのインデックスを作成する
   • 統計情報を計算する

4. テンプレートをレンダリングする

   • Jinja2 テンプレートを適用する
   • ドキュメントファイルを生成する
   • docs/ ディレクトリに書き込む

使用方法

# Generate all documentation files
python doc_generator.py

# Generate specific file only
python doc_generator.py --file agents

# Dry run (show output without writing)
python doc_generator.py --dry-run

# Specify custom paths
python doc_generator.py \
  --marketplace .claude-plugin/marketplace.json \
  --templates plugins/claude-plugin/skills/documentation-update/assets \
  --output docs

コマンドとの統合

/claude-plugin:create コマンドと /claude-plugin:update コマンドは、マーケットプレイスの更新後にこのスキルを自動的に呼び出す必要があります。

ワークフロー

1. Plugin operation completes (add/update/remove)
2. Marketplace.json is updated
3. Invoke documentation-update skill
4. Documentation files regenerated
5. Changes ready to commit

統合例

# After creating/updating plugin
print("Updating documentation...")

# Run doc generator
import subprocess
result = subprocess.run(
    ["python", "plugins/claude-plugin/skills/documentation-update/doc_generator.py"],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("✓ Documentation updated")
else:
    print(f"❌ Documentation update failed: {result.stderr}")

テンプレートの例

agents.md.j2

# Agent Reference

This document lists all agents available across plugins in the marketplace.

{% for category, plugins in plugins_by_category.items() %}
## {{ category|title }}

{% for plugin in plugins %}
### {{ plugin.name }}

{{ plugin.description }}

**Agents:**

{% for agent in all_agents %}
{% if agent.plugin == plugin.name %}
- **{{ agent.name }}** (`{{ agent.model }}`)
  - {{ agent.description }}
  - File: `plugins/{{ plugin.name }}/agents/{{ agent.file }}`
{% endif %}
{% endfor %}

{% endfor %}
{% endfor %}

---
*Last updated: {{ now }}*
*Total agents: {{ stats.total_agents }}*

agent-skills.md.j2

# Agent Skills Reference

This document catalogs all skills with progressive disclosure patterns.

{% for plugin in marketplace.plugins %}
## {{ plugin.name }}

{{ plugin.description }}

**Skills:**

{% for skill in all_skills %}
{% if skill.plugin == plugin.name %}
### {{ skill.name }}

{{ skill.description }}

- **Location:** `plugins/{{ plugin.name }}/skills/{{ skill.path }}/`
- **Structure:** SKILL.md + assets/ + references/

{% endif %}
{% endfor %}

{% endfor %}

---
*Last updated: {{ now }}*
*Total skills: {{ stats.total_skills }}*

エラー処理

マーケットプレイスが見つからない場合

Error: Marketplace file not found: .claude-plugin/marketplace.json
Suggestion: Ensure marketplace.json exists

テンプレートが見つからない場合

Error: Template file not found: assets/agents.md.j2
Suggestion: Ensure all template files exist in assets/

プラグイン構造が無効な場合

Warning: Plugin 'plugin-name' missing components
Suggestion: Verify plugin has agents or commands

Frontmatter の解析エラー

Warning: Could not parse frontmatter in agents/agent-name.md
Suggestion: Check YAML frontmatter syntax

ベストプラクティス

1. 変更後は必ず再生成する

   • プラグインの追加・更新・削除後に実行する
   • ドキュメントの同期状態を維持する
   • ドキュメントをプラグインの変更とともにコミットする

2. 生成前に検証する

   • まずマーケットプレイスの検証を実行する
   • エラーや警告を修正する
   • すべてのファイルが存在することを確認する

3. 生成された出力を確認する

   • 生成されたファイルが正しいか確認する
   • 書式とリンクを検証する
   • コード例をテストする

4. テンプレートを保守する

   • テンプレートをシンプルで読みやすく保つ
   • 一貫した書式を使用する
   • テンプレート変数を説明する

5. バージョン管理

   • ドキュメントの変更をコミットする
   • プルリクエストに含める
   • 重要な変更を記録する

テンプレートのカスタマイズ

セクションの追加

テンプレートに新しいセクションを追加するには、以下の手順を実行します。

1. テンプレートを変更する

   ## New Section
   
   {% for plugin in marketplace.plugins %}
   ### {{ plugin.name }}
   [Your content here]
   {% endfor %}
   

2. コンテキストを更新する（必要な場合）

   • doc_generator.py のテンプレートコンテキストに新しいデータを追加する
   • 追加のメタデータを処理する

3. 出力をテストする

   • ドライランでジェネレーターを実行する
   • 書式を確認する
   • エラーがないか確認する

新しいテンプレートの作成

新しいドキュメントファイルを追加するには：

1. テンプレートを作成

   • assets/newdoc.md.j2 を追加します
   • 構造と内容を定義します

2. スクリプトを更新

   • doc_generator.py のテンプレート一覧に追加します
   • 出力先を定義します

3. 生成をテスト

   • ジェネレーターを実行します
   • 出力を確認します
   • テンプレートと出力をコミットします

ファイル構成

plugins/claude-plugin/skills/documentation-update/
├── SKILL.md                      # This file
├── doc_generator.py              # Python implementation
├── assets/                       # Jinja2 templates
│   ├── agents.md.j2
│   ├── agent-skills.md.j2
│   ├── plugins.md.j2
│   └── usage.md.j2
└── references/                   # Optional examples
    └── template-examples.md

要件

• Python 3.8+
• 外部依存関係なし（標準ライブラリのみを使用）
• .claude-plugin/marketplace.json へのアクセス権
• プラグインディレクトリへの読み取り権限
• docs/ ディレクトリへの書き込み権限

成功基準

このスキルを実行すると、次の状態になります。

• ✓ すべてのドキュメントファイルが生成されている
• ✓ 内容がマーケットプレイスの状態と一致している
• ✓ すべてのリンクが有効である
• ✓ 書式が統一されている
• ✓ 統計情報が正確である
• ✓ テンプレートのレンダリングエラーがない

メンテナンス

テンプレートの更新

マーケットプレイスの構造が変更された場合：

1. 影響を評価

   • 影響を受けるテンプレートを特定します
   • 必要な変更を判断します

2. テンプレートを更新

   • Jinja2 テンプレートを変更します
   • 現在のデータでテストします

3. スクリプトを更新

   • 必要に応じてコンテキストの準備を調整します
   • 新しいデータ処理を追加します

4. 出力を検証

   • すべてのドキュメントを再生成します
   • 変更を確認します
   • リンクと書式をテストします

バージョン互換性

• テンプレートは欠落しているフィールドを適切に処理する必要があります
• オプションデータには Jinja2 の default フィルターを使用します
• マーケットプレイスのバージョン互換性を検証します

出力例

このスキルは、包括的で適切に書式設定されたドキュメントを生成します。

• agents.md：20～30 個のエージェントに対して約 500～1000 行
• agent-skills.md：30～50 個のスキルに対して約 300～600 行
• plugins.md：10～20 個のプラグインに対して約 400～800 行
• usage.md：使用方法に関する情報が約 200～400 行

すべてのファイルには、次の内容が含まれます。

• 明確な構成と見出し
• 適切な箇所に整形された表
• ソースファイルへのリンク
• 統計情報とメタデータ
• 最終更新日時