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を作成できます。