docs-sync

/docs:sync [OPTIONS]

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

次のような場合にこのスキルを使用します…	次のような場合は docs-generate を使用します…
README または CLAUDE.md に記載されたスキル／コマンド／エージェントの数が、実際にディレクトリにある数と一致しなくなった場合	コードを基に、新しい API リファレンス、README の書き換え、または CHANGELOG の内容を作成する場合
新しいスキルが追加されたものの、カタログの表にまだ記載されていない場合	カタログ自体に問題はなく、新しいドキュメントを作成する必要がある場合
削除された項目が、古いエントリーとしてドキュメントに残っている場合	サービス終了のチェックリストを作成する場合（docs-decommission を使用）
リファクタリング後に、相互参照やカテゴリの分類を調整する必要がある場合	既存の Markdown ドキュメントを印刷用の PDF に変換する場合（docs-latex を使用）

コードベースをスキャンしてスキル、コマンド、エージェントを確認し、すべてのドキュメントを現在の状態に合わせて更新します。項目数の不一致を修正し、足りないエントリーを追加し、古い参照を削除します。

使用方法

/docs:sync                        # Sync all documentation
/docs:sync --scope skills         # Only sync skill documentation
/docs:sync --scope commands       # Only sync command documentation
/docs:sync --scope agents         # Only sync agent documentation
/docs:sync --dry-run              # Show what would change without modifying
/docs:sync --verbose              # Show detailed scanning output

パラメーター

• --scope <type> - 同期する種類を skills、commands、agents、または all（デフォルト）に限定します
• --dry-run - ファイルを変更せずに変更内容をプレビューします
• --verbose - スキャン中の詳細な進行状況を表示します

実行

次のドキュメント同期ワークフローを実行します。

ステップ 1：コードベースの項目を検出する

1. ソースディレクトリをスキャンします：

   # Skills
   find .claude/skills -name "SKILL.md" -type f
   
   # Commands
   find .claude/commands -name "*.md" -type f ! -name "CLAUDE.md"
   
   # Agents
   find .claude/agents -name "*.md" -type f
   

2. 各項目からメタデータを抽出します：

   • スキル：YAML フロントマターから name と description を解析します
   • コマンド：フロントマターから description を解析し、パスから名前空間を推定します
   • エージェント：フロントマターから name、description、tools を解析します

3. 既存のドキュメントを解析します：

   • .claude/skills/CLAUDE.md - カテゴリ別の現在のスキルカタログ
   • .claude/skills/CLAUDE.md - 名前空間別のコマンドリファレンス
   • ルートの CLAUDE.md - 概要の件数と主な項目

ステップ 2：差分を分析する

1. 実際の状態とドキュメントを比較します：

   • ディレクトリにはあるがドキュメントに記載されていない項目を検出します（新規）
   • ドキュメントには記載されているがディレクトリにない項目を検出します（古い項目）
   • 件数が一致しているか確認します

2. 新しい項目を分類します：

   スキルの場合、次の方法でカテゴリを決定します。

   • 名前のパターン：ux-*、git-*、python-* → 対応するカテゴリ
   • 説明内のキーワード：「accessibility」、「testing」、「infrastructure」
   • 同じ分野にある既存の類似スキル
   • 判断できない場合は、手動確認用に「未分類」を提案します

   ユーザーが呼び出せるスキルの場合、ディレクトリ名から名前空間を決定します。

   • skills/git-commit/SKILL.md → git: 名前空間
   • skills/handoffs/SKILL.md → ルートレベル

   エージェントの場合、説明内のキーワードから分野を決定します

3. 更新するドキュメントのセクションを特定します：

   • 件数のパターン：**N skills**、N total、(N skills)
   • カテゴリ／名前空間別のリストセクション
   • 概要表

ステップ 3：更新を適用する

1. ドキュメント全体の件数を更新します：

   • **63 skills** や 63 specialized skills のようなパターンを検索します
   • 正確な件数に置き換えます
   • ### Core Development (9 skills) のようなカテゴリ別の件数を更新します

2. 適切なセクションに新しい項目を追加します：

   スキルカタログの形式：

   ### Category Name (N skills)
   - **skill-name** - Description from SKILL.md frontmatter
   

   コマンド表の形式：

   | Namespace | Commands | Purpose |
   | `/command` | Description | Usage context |
   

   エージェント一覧の形式：

   | Agent | Purpose | Key Tools |
   | **agent-name** | Description | Tool1, Tool2 |
   

3. コードベースに存在しない古いエントリーを削除します

4. 相互参照を更新します：

   • 「関連項目」セクション
   • 関連するスキル／コマンドの一覧

ステップ 4：結果を報告する

変更内容の概要を生成します。

## Documentation Sync Report

### Skills
- ✅ Added N new skills to catalog
  - skill-name → Category Name
- ✅ Removed N stale skills
- ✅ Updated skill count: OLD → NEW

### Commands
- ✅ Added N new commands
  - /namespace:command → Description
- ✅ Updated command counts

### Agents
- ✅ Added N new agents
  - agent-name → Domain
- ✅ Updated agent inventory

### Files Modified
- path/to/file.md (N changes)

### Manual Review Needed
- item-name: Could not determine category

更新するドキュメントファイル

主な対象（必ず確認）：

• .claude/skills/CLAUDE.md - スキルカタログ
• .claude/skills/CLAUDE.md - コマンドリファレンス
• CLAUDE.md（ルート） - リポジトリの概要

その他の対象（存在する場合）：

• README.md - プロジェクトの README
• docs/ ディレクトリのコンテンツ
• スキル／コマンド／エージェントの件数が記載されたファイル

分類ルール

スキルカテゴリ

パターン	カテゴリ
ux-*、accessibility-*、design-*	UX とアクセシビリティ
git-*、github-*	バージョン管理と GitHub
python-*、uv-*、ruff-*	Python 開発
typescript-*、nodejs-*、vitest-*	TypeScript/JavaScript
rust-*、cpp-*、embedded-*	システム言語
container-*、kubernetes-*、helm-*、terraform-*	インフラストラクチャと DevOps
test-*、playwright-*、mutation-*	テストと品質
agent-*、multi-agent-*	メタと調整

スキルの名前空間

スキルのディレクトリ名のプレフィックスで決まります。

• skills/git-*/SKILL.md → git: 名前空間
• skills/docs-*/SKILL.md → docs: 名前空間
• skills/*/SKILL.md（プレフィックスなし） → ルートレベルのスキル

エラー処理

• ドキュメントファイルが見つからない場合：発見した内容を使ってテンプレートから作成します
• YAML フロントマターの形式が不正な場合：警告を出して項目をスキップし、概要に報告します
• 分類が曖昧な場合：「未分類」セクションに追加し、レビュー対象として示します
• エントリが重複している場合：警告を出し、最初の項目を残します

ベストプラクティス

1. 機能の追加後に実行する - 実装とドキュメントを同期した状態に保ちます
2. まずドライランを確認する - 適用する前に分類を確認します
3. ドキュメントは個別にコミットする - docs: の Conventional Commit プレフィックスを使用します
4. 相互参照を確認する - 「関連項目」セクションが更新されていることを確認します

セッション例

# After adding new skills
/docs:sync --dry-run

# Review output, then apply
/docs:sync

# Commit the documentation updates
git add .claude/
git commit -m "docs: sync documentation with new UX implementation features"

関連項目

• コマンド：新しいドキュメントを生成するには /docs:generate を使用します
• スキル：自動バージョニングには release-please-protection を使用します
• ワークフロー：/project:new の実行後、または大規模な機能追加後に実行します