Gardening Skills Wiki

ガーデニングスキル Wiki

概要

スキル Wiki を健全な状態に保つには、定期的なメンテナンスが必要です。リンク切れ、孤立したスキル、命名の不統一、INDEX ファイルとの同期ずれが発生します。

基本原則： 手作業での確認にトークンを消費せず、ヘルスチェックを自動化して Wiki の品質を維持します。

使用するタイミング

次の場合はガーデニングを実行してください：

• 新しいスキルを追加した後
• スキルを削除または名前変更した後
• カテゴリーを再編成した後
• 相互参照を更新した後
• リンク切れが疑われる場合

定期メンテナンス：

• 活発に開発している期間は毎週
• 安定している期間は毎月

簡易ヘルスチェック

# Run all checks
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# Or run specific checks
~/.claude/skills/meta/gardening-skills-wiki/check-links.sh
~/.claude/skills/meta/gardening-skills-wiki/check-naming.sh
~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh

# Analyze search gaps (what skills are missing)
~/.claude/skills/meta/gardening-skills-wiki/analyze-search-gaps.sh

マスタースクリプトを実行すると、すべてのチェックが行われ、ヘルスレポートが表示されます。

チェック項目

1. リンク検証（check-links.sh）

チェック内容：

• バッククォートで囲まれた @ リンク — バッククォートによって解決が無効になります
• skills/ や skills/gardening-skills-wiki/~/ のような相対パス — skills/ の絶対パスを使用してください
• すべての skills/ 参照が既存のファイルに解決されること
• INDEX ファイルで参照されているスキルが存在すること
• 孤立したスキル（いずれの INDEX にも記載されていないスキル）

修正内容：

• @ 参照からバッククォートを削除
• skills/ および skills/gardening-skills-wiki/~/ の相対パスを skills/ の絶対パスに変換
• 壊れた skills/ 参照を正しいパスに更新
• 孤立したスキルを該当カテゴリーの INDEX に追加
• 削除されたスキルへの参照を削除

2. 命名の一貫性（check-naming.sh）

チェック内容：

• ディレクトリ名が kebab-case であること
• ディレクトリ名に大文字やアンダースコアが含まれていないこと
• Frontmatter のフィールド（name、description、when_to_use、version、type）が存在すること
• スキル名が能動態であること（「How to...」ではないこと）
• 空のディレクトリ

修正内容：

• ディレクトリ名を kebab-case に変更
• 不足している frontmatter フィールドを追加
• 空のディレクトリを削除
• 名前を能動態に言い換え

3. INDEX の網羅性（check-index-coverage.sh）

チェック内容：

• すべてのスキルが該当カテゴリーの INDEX に記載されていること
• すべてのカテゴリー INDEX ファイルがメイン INDEX からリンクされていること
• INDEX の項目にスキルの説明があること

修正内容：

• 不足しているスキルを INDEX ファイルに追加
• カテゴリーへのリンクをメイン INDEX に追加
• INDEX の項目に説明を追加

よくある問題と修正方法

リンク切れ

❌ BROKEN: skills/debugging/root-cause-tracing
   Target: /path/to/skills/debugging/root-cause-tracing/SKILL.md

修正： 参照パスを更新します。スキルが移動または名前変更されている可能性があります。

孤立したスキル

⚠️  ORPHANED: test-invariants/SKILL.md not in testing/INDEX.md

修正： 該当カテゴリーの INDEX に追加します。

- skills/gardening-skills-wiki/test-invariants - Description of skill

バッククォートで囲まれたリンク

❌ BACKTICKED: skills/testing/condition-based-waiting on line 31
   File: getting-started/SKILL.md
   Fix: Remove backticks - use bare @ reference

修正： バッククォートを削除します。

# ❌ Bad - backticks disable link resolution
`skills/testing/condition-based-waiting`

# ✅ Good - bare @ reference
skills/testing/condition-based-waiting

相対パスのリンク

❌ RELATIVE: skills/testing in coding/SKILL.md
   Fix: Use skills/ absolute path instead

修正： 絶対パスに変換します。

# ❌ Bad - relative paths are brittle
skills/testing/condition-based-waiting

# ✅ Good - absolute skills/ path
skills/testing/condition-based-waiting

命名の問題

⚠️  Mixed case: TestingPatterns (should be kebab-case)

修正： ディレクトリ名を変更します。

cd ~/.claude/skills/testing
mv TestingPatterns testing-patterns
# Update all references to old name

INDEX に未記載

❌ NOT INDEXED: condition-based-waiting/SKILL.md

修正： testing/INDEX.md に追加します。

## Available Skills

- skills/gardening-skills-wiki/condition-based-waiting - Replace timeouts with condition polling

空のディレクトリ

⚠️  EMPTY: event-based-testing

修正： 不要になった場合は削除します。

rm -rf ~/.claude/skills/event-based-testing

命名規則

ディレクトリ名

• 形式： kebab-case（小文字とハイフン）
• プロセススキル： 適切な場合は動名詞を使用します（creating-skills、testing-skills）
• パターンスキル： 中心となる概念を使用します（flatten-with-flags、test-invariants）
• 避けるもの： 大文字と小文字の混在、アンダースコア、受動態で始まる名前（「how-to-」）

Frontmatter の要件

必須フィールド：

• name：人が読める名前
• description：1 行の概要
• when_to_use：症状や状況（CSO に必須）
• version：セマンティックバージョン

任意フィールド：

• languages：該当する言語
• dependencies：必要なツール
• context：特別なコンテキスト（例：「AI 支援開発」）

自動化ワークフロー

新しいスキルを追加した後

# 1. Create skill
mkdir -p ~/.claude/skills/category/new-skill
vim ~/.claude/skills/category/new-skill/SKILL.md

# 2. Add to category INDEX
vim ~/.claude/skills/category/INDEX.md

# 3. Run health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# 4. Fix any issues reported

再編成した後

# 1. Move/rename skills
mv ~/.claude/skills/old-category/skill ~/.claude/skills/new-category/

# 2. Update all references (grep for old paths)
grep -r "skills/gardening-skills-wiki/old-category/skill" ~/.claude/skills/

# 3. Run health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# 4. Fix broken links

定期メンテナンス

# Monthly: Run full health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# Review and fix:
# - ❌ errors (broken links, missing skills)
# - ⚠️  warnings (naming, empty dirs)

スクリプト

garden.sh（マスター）

すべてのヘルスチェックを実行し、包括的なレポートを表示します。

使用方法：

~/.claude/skills/meta/gardening-skills-wiki/garden.sh [skills_dir]

check-links.sh

すべての @ 参照と相互リンクを検証します。

チェック内容：

• バッククォートで囲まれた @ リンク（解決が無効になります）
• 相対パス（skills/ または skills/gardening-skills-wiki/~/）— skills/ を使用してください
• @ 参照が既存のファイルに解決されること
• INDEX ファイル内のスキルが存在すること
• 孤立したスキルの検出

check-naming.sh

命名規則とフロントマターを検証します。

チェック項目:

• ディレクトリ名の形式
• フロントマターの完全性
• 空のディレクトリ

check-index-coverage.sh

INDEX の完全性を検証します。

チェック項目:

• カテゴリ INDEX に掲載されているスキル
• メイン INDEX にリンクされているカテゴリ
• 説明が存在すること

クイックリファレンス

問題	スクリプト	修正
バッククォートで囲まれたリンク	check-links.sh	@ 参照からバッククォートを削除
相対パス	check-links.sh	skills/ 絶対パスに変換
壊れたリンク	check-links.sh	@ 参照を更新
孤立したスキル	check-links.sh	INDEX に追加
命名の問題	check-naming.sh	ディレクトリ名を変更
空のディレクトリ	check-naming.sh	rm -rf で削除
INDEX に存在しない	check-index-coverage.sh	INDEX.md に追加
説明がない	check-index-coverage.sh	INDEX エントリに追加

出力記号

• ✅ 合格 - 項目は正しい
• ❌ エラー - 修正必須（壊れたリンク、存在しないスキル）
• ⚠️ 警告 - 修正すべき（命名、空のディレクトリ）
• ℹ️ 情報 - 参考情報（対応不要）

ワークフローとの統合

スキルの変更をコミットする前に:

~/.claude/skills/meta/gardening-skills-wiki/garden.sh
# Fix all ❌ errors
# Consider fixing ⚠️  warnings
git add .
git commit -m "Add/update skills"

リンクに疑わしい点がある場合:

~/.claude/skills/meta/gardening-skills-wiki/check-links.sh

INDEX が不完全に思える場合:

~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh

よくある言い訳

言い訳	現実
「リンクは手動で確認する」	自動チェックの方が速く、より徹底的です
「INDEX はおそらく問題ない」	孤立したスキルは発生します - 常に検証してください
「命名は重要ではない」	一貫性は発見と保守に役立ちます
「空のディレクトリは無害」	乱雑さは将来の保守担当者を混乱させます
「定期的なチェックは省略できる」	問題は積み重なります - 定期的なメンテナンスが大規模なクリーンアップを防ぎます

実際の影響

ガーデニングなしの場合:

• 緊急のタスク中に壊れたリンクが発見される
• 孤立したスキルが永久に見つからない
• 時間の経過とともに命名がずれる
• INDEX ファイルが同期から外れる

ガーデニングありの場合:

• 30秒のヘルスチェックで問題を早期に発見
• 自動検証により手動検査が不要に
• 一貫した構造が発見を助ける
• Wiki が保守可能な状態を維持

結論

手動で検査しないでください - チェックを自動化しましょう。

変更後および定期的に garden.sh を実行してください。❌ エラーはすぐに修正し、⚠️ 警告は都合の良いときに解決してください。

保守された Wiki = 発見できるスキル = 再利用可能な知識。