majiayu000 Skill Design Principles（SKILL設計原則）
目的
高品質で実用的なSKILLを作成・維持するための設計原則とベストプラクティスを提供します。今回の学びから得られた「ハードガードレールとソフトガードレールの使い分け」「用途を絞る」などの重要な原則を含みます。
いつアクティベートするか
- 新しいSKILLを作成する時
- 既存のSKILLをレビュー・改善する時
- SKILLが適切かどうか判断する時
- CLAUDE.mdからSKILL化すべき内容を検討する時
クイックチェックリスト
SKILL作成前
- 特定のタスクに特化している（広範囲すぎない）
- ハードガードレールで担保されていない（CI、hookで防げることは書かない）
- 実用的なガイダンスを提供できる（単なるルールの羅列ではない）
- 既存のSKILLと重複していない
SKILL作成中
- アクティベーション条件が明確
- 具体的なコード例を含む
- チェックリストが実用的
- 「良い例」と「悪い例」を対比
SKILL作成後
- タイトルとdescriptionが一致している
- アクティベーション条件が狭すぎず広すぎない
- 他のSKILLとの関連性が明確
- CLAUDE.mdのSkill Usage Guideに追加
設計原則
原則1: ハードガードレールとソフトガードレールを区別する
ハードガードレール
定義: 自動的に強制される制約（CI、Pre-commit hooks、型チェックなど）
特徴:
- 違反すると自動的にエラーが発生
- 人間の判断が不要
- 100%の強制力
例:
- Pre-commit hooks（ruff、pyright、pytest）
- CI/CDでの自動テスト
- 型チェック（mypy、pyright）
- Linter（ruff、eslint）
⚠️ 重要: ハードガードレールで担保されている要素はSKILLに書かなくてもいい
ソフトガードレール
定義: 人間の判断が必要な制約（設計判断、命名、構造など）
特徴:
- 違反してもエラーにならない
- 人間の判断が必要
- SKILLで提供すべき内容
例:
- ファイル配置ルール（
tmp/ディレクトリの使用） - アーキテクチャ原則（Clean Architecture）
- 命名規則
- データ処理の順序
判断フロー
新しいルールを追加したい
↓
Q: CIやhookで自動的にチェックできる？
↓
YES → ハードガードレール
→ CI/hookに追加（SKILLには書かない）
↓
NO → ソフトガードレール
→ SKILLに追加
良い例・悪い例
❌ 悪い例：ハードガードレールをSKILLに書く
## チェックリスト
- [ ] ruff checkが通っている
- [ ] pyrightが通っている
- [ ] テストが成功している
理由: これらはPre-commit hooksとCIで自動的にチェックされる。SKILLに書く必要がない。
✅ 良い例：ソフトガードレールをSKILLに書く
## チェックリスト
- [ ] 一時ファイルは`tmp/`ディレクトリに作成している
- [ ] ファイル名にタイムスタンプを含めている
- [ ] pathlibを使用している
理由: これらは自動的にチェックできないため、SKILLで提供すべき。
原則2: 用途をできるだけ絞る
特定のタスクに特化する
推奨: 1つのSKILLは1つの特定のタスク・分野に特化する
良い例:
- ✅
temp-file-management: 一時ファイル管理に特化 - ✅
migration-helper: データベースマイグレーションに特化 - ✅
git-branch-cleanup: Gitブランチ整理に特化
悪い例:
- ❌
critical-requirements: 広範囲すぎる（コミット、ファイル作成、データ処理、テスト、GCS操作など） - ❌
development-rules: 抽象的すぎる
アクティベーション条件の粒度
良い例:
## いつアクティベートするか
- 一時ファイルを作成する時
- 中間ファイルを作成する時
- ファイルパスを指定する時
悪い例:
## いつアクティベートするか
- git commitを実行する前
- 新しいファイルを作成する時
- データ処理を実行する時
- テストを書く時
- GCS操作を行う時
- データベースマイグレーションを作成する時
理由: 後者は広範囲すぎて、特定のタスクに対する具体的なガイダンスを提供できない。
原則3: 実用的なガイダンスを提供する
具体的なコード例を含める
推奨: 「良い例」と「悪い例」を対比させる
良い例:
**✅ 良い例：pathlibを使用**
```python
from pathlib import Path
output_path = Path("tmp/result.json")
❌ 悪い例：文字列連結
output_path = "tmp/" + "result.json"
---
#### チェックリストは実用的に
**推奨**: 実際に確認できる項目のみを含める
**良い例**:
```markdown
- [ ] ファイル名にタイムスタンプを含めている
- [ ] pathlibを使用している
- [ ] ディレクトリを自動作成している
悪い例:
- [ ] コードが読みやすい
- [ ] 適切に設計されている
- [ ] ベストプラクティスに従っている
理由: 後者は抽象的すぎて、何をチェックすべきか不明確。
原則4: 既存のSKILLと重複しない
重複チェック
新しいSKILLを作成する前に、既存のSKILLと重複していないか確認する。
チェック方法:
.claude/skills/ディレクトリを確認- CLAUDE.mdのSkill Usage Guideを確認
- 類似のアクティベーション条件がないか確認
統合 vs 分割
統合すべき場合:
- 2つのSKILLが密接に関連している
- アクティベーション条件が重複している
- 一方が他方のサブセットになっている
分割すべき場合:
- 1つのSKILLが広範囲すぎる
- 異なるタスクをカバーしている
- アクティベーション条件が明確に異なる
SKILL作成ワークフロー
ステップ1: 用途を明確化
以下の質問に答える：
何を支援するSKILLか？
- 例：「一時ファイル管理」「Gitブランチ整理」
いつアクティベートするか？
- 例：「一時ファイルを作成する時」
ハードガードレールで担保できるか？
- NO → SKILLとして作成
- YES → CI/hookに追加（SKILLには書かない）
ステップ2: スコープを絞る
チェック項目:
- アクティベーション条件が3-5個以内
- 特定のタスク・分野に特化している
- 既存のSKILLと重複していない
ステップ3: 内容を構成する
必須セクション:
- フロントマター（name、description）
- 目的
- いつアクティベートするか
- クイックチェックリスト
- 詳細なガイドライン（具体例付き）
任意セクション:
- リファレンス
- 完全な実装例
- トラブルシューティング
ステップ4: レビュー
チェック項目:
- ハードガードレールで担保できる内容を含んでいない
- 用途が絞られている（広範囲すぎない）
- 具体的なコード例を含んでいる
- チェックリストが実用的
- アクティベーション条件が明確
良いSKILLの例
temp-file-management
特徴:
- ✅ 一時ファイル管理に特化
- ✅ 具体的なコード例が豊富
- ✅ ハードガードレールで担保できない内容
- ✅ 実用的なチェックリスト
アクティベーション条件:
- 一時ファイルを作成する時
- 中間ファイルを作成する時
- ファイルパスを指定する時
git-branch-cleanup
特徴:
- ✅ Gitブランチ整理に特化
- ✅ 5ステップのワークフローを提供
- ✅ 安全ガードの実装例
- ✅ 完全なスクリプト例
アクティベーション条件:
- ユーザーが「ブランチを整理」と依頼した時
- ユーザーが「古いブランチを削除」と依頼した時
悪いSKILLの例
critical-requirements（削除済み）
問題点:
- ❌ 広範囲すぎる（コミット、ファイル作成、データ処理、テスト、GCS操作など）
- ❌ ハードガードレールで担保できる内容を含む（Pre-commit hooks、CI/CD）
- ❌ 特定のタスクに対する具体的なガイダンスがない
アクティベーション条件（広すぎる）:
- git commitを実行する前
- 新しいファイルを作成する時
- データ処理を実行する時
- テストを書く時
- GCS操作を行う時
- データベースマイグレーションを作成する時
既存のSKILLをレビューする
レビュー観点
ハードガードレールチェック
- CI/hookで担保できる内容が含まれていないか？
- 含まれていれば削除する
スコープチェック
- 広範囲すぎないか？
- 特定のタスクに特化しているか？
実用性チェック
- 具体的なコード例があるか？
- チェックリストが実用的か？
改善フロー
既存のSKILLをレビュー
↓
Q: ハードガードレールで担保できる内容が含まれている？
↓
YES → 該当部分を削除
↓
Q: 広範囲すぎる？
↓
YES → 複数のSKILLに分割
↓
Q: 実用的なガイダンスがない？
↓
YES → コード例とチェックリストを追加
↓
改善完了
リファレンス
- skill-creator: SKILL作成の基本テンプレート
- temp-file-management: 良いSKILLの例
- git-branch-cleanup: 良いSKILLの例
まとめ
このSKILLは、高品質で実用的なSKILLを作成・維持するための設計原則を提供します。
重要な原則
✅ ハードガードレールで担保できる内容は書かない（CI、hookで防げることはSKILLに含めない） ✅ 用途をできるだけ絞る（特定のタスク・分野に特化する） ✅ 実用的なガイダンスを提供する（具体的なコード例、実用的なチェックリスト） ✅ 既存のSKILLと重複しない（重複チェックを実施）
これらの原則に従うことで、特定のタスクに対して具体的で実用的なガイダンスを提供できるSKILLを作成できます。