shield_lock
JinDaGe
← Back to skills
extension
Category: AI Agent CapabilitiesNo API key required

skill-design-principles

Provides design principles and best practices for creating and organizing SKILL. It covers principles such as 'do not write elements guaranteed by hard guardrails' and 'narrow down the purpose as much as possible.' Activate these when creating a new SKILL or reviewing existing ones.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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と重複していないか確認する。

チェック方法:

  1. .claude/skills/ディレクトリを確認
  2. CLAUDE.mdのSkill Usage Guideを確認
  3. 類似のアクティベーション条件がないか確認

統合 vs 分割

統合すべき場合:

  • 2つのSKILLが密接に関連している
  • アクティベーション条件が重複している
  • 一方が他方のサブセットになっている

分割すべき場合:

  • 1つのSKILLが広範囲すぎる
  • 異なるタスクをカバーしている
  • アクティベーション条件が明確に異なる

SKILL作成ワークフロー

ステップ1: 用途を明確化

以下の質問に答える：

  1. 何を支援するSKILLか？

    • 例：「一時ファイル管理」「Gitブランチ整理」

  2. いつアクティベートするか？

    • 例：「一時ファイルを作成する時」

  3. ハードガードレールで担保できるか？

    • NO → SKILLとして作成
    • YES → CI/hookに追加（SKILLには書かない）

ステップ2: スコープを絞る

チェック項目:

  • [ ] アクティベーション条件が3-5個以内
  • [ ] 特定のタスク・分野に特化している
  • [ ] 既存のSKILLと重複していない

ステップ3: 内容を構成する

必須セクション:

  1. フロントマター（name、description）
  2. 目的
  3. いつアクティベートするか
  4. クイックチェックリスト
  5. 詳細なガイドライン（具体例付き）

任意セクション:

  • リファレンス
  • 完全な実装例
  • トラブルシューティング

ステップ4: レビュー

チェック項目:

  • [ ] ハードガードレールで担保できる内容を含んでいない
  • [ ] 用途が絞られている（広範囲すぎない）
  • [ ] 具体的なコード例を含んでいる
  • [ ] チェックリストが実用的
  • [ ] アクティベーション条件が明確

良いSKILLの例

temp-file-management

特徴:

  • ✅ 一時ファイル管理に特化
  • ✅ 具体的なコード例が豊富
  • ✅ ハードガードレールで担保できない内容
  • ✅ 実用的なチェックリスト

アクティベーション条件:

  • 一時ファイルを作成する時
  • 中間ファイルを作成する時
  • ファイルパスを指定する時

git-branch-cleanup

特徴:

  • ✅ Gitブランチ整理に特化
  • ✅ 5ステップのワークフローを提供
  • ✅ 安全ガードの実装例
  • ✅ 完全なスクリプト例

アクティベーション条件:

  • ユーザーが「ブランチを整理」と依頼した時
  • ユーザーが「古いブランチを削除」と依頼した時

悪いSKILLの例

critical-requirements（削除済み）

問題点:

  • ❌ 広範囲すぎる（コミット、ファイル作成、データ処理、テスト、GCS操作など）
  • ❌ ハードガードレールで担保できる内容を含む（Pre-commit hooks、CI/CD）
  • ❌ 特定のタスクに対する具体的なガイダンスがない

アクティベーション条件（広すぎる）:

  • git commitを実行する前
  • 新しいファイルを作成する時
  • データ処理を実行する時
  • テストを書く時
  • GCS操作を行う時
  • データベースマイグレーションを作成する時

既存のSKILLをレビューする

レビュー観点

  1. ハードガードレールチェック

    • CI/hookで担保できる内容が含まれていないか？
    • 含まれていれば削除する

  2. スコープチェック

    • 広範囲すぎないか？
    • 特定のタスクに特化しているか？

  3. 実用性チェック

    • 具体的なコード例があるか？
    • チェックリストが実用的か？

改善フロー

既存のSKILLをレビュー
↓
Q: ハードガードレールで担保できる内容が含まれている？
↓
YES → 該当部分を削除
↓
Q: 広範囲すぎる？
↓
YES → 複数のSKILLに分割
↓
Q: 実用的なガイダンスがない？
↓
YES → コード例とチェックリストを追加
↓
改善完了

リファレンス

まとめ

このSKILLは、高品質で実用的なSKILLを作成・維持するための設計原則を提供します。

重要な原則

✅ ハードガードレールで担保できる内容は書かない（CI、hookで防げることはSKILLに含めない） ✅ 用途をできるだけ絞る（特定のタスク・分野に特化する） ✅ 実用的なガイダンスを提供する（具体的なコード例、実用的なチェックリスト） ✅ 既存のSKILLと重複しない（重複チェックを実施）

これらの原則に従うことで、特定のタスクに対して具体的で実用的なガイダンスを提供できるSKILLを作成できます。