accelint-skill-manager

スキルマネージャー

スキル作成時に絶対にしてはいけないこと

• 基本事項を説明するチュートリアルは絶対に書かないでください — Claude は標準的な概念、ライブラリ、パターンを理解しているものとします。専門家だけが知る情報に焦点を当ててください。
• 起動条件を本文に記載しないでください — 「使用するタイミング」のガイダンスは、説明フィールドにのみ記載してください。本文は起動の判断後に読み込まれます。
• すべての情報を SKILL.md に詰め込まないでください — 段階的な開示を活用してください。中核となるワークフローは SKILL.md（理想は 500 行未満）にまとめ、詳細は references/ に記載して必要に応じて読み込みます。
• 一般的な警告を使わないでください — 「注意してください」や「エラーを避けてください」は役に立ちません。具体的な理由を添えて、避けるべきパターンを示してください。
• すべてのタスクで同じ自由度にしないでください — 創造的な分野（デザイン、アーキテクチャ）では原則に基づく高い自由度が必要です。壊れやすい操作（ファイル形式、API）では、正確なスクリプトを使う低い自由度が必要です。
• 標準的な操作を説明しないでください — Claude はファイルの読み込み、コードの記述、一般的なライブラリの使用方法を理解しているものとします。見落としやすい判断やエッジケースに焦点を当ててください。
• 明白な手順を含めないでください — 「ステップ 1：ファイルを開く、ステップ 2：編集する、ステップ 3：保存する」はトークンの無駄です。Claude が知らない、分野固有のワークフローだけを含めてください。
• アンチパターンのセクションを省略しないでください — 専門知識の半分を占める部分です。「絶対にしてはいけないこと」がないスキルには、価値の源である、専門家が経験から学んだ失敗例が欠けています。
• 曖昧な説明を書かないでください — 「X のスキル」のような説明では誤検知や起動漏れが発生します。実際にユーザーが使う具体的なトリガーフレーズを説明に含めてください。
• 作成と監査の関心事を混在させないでください — スキルの作成、リファクタリング、監査は、それぞれ異なるワークフローです。入力、出力、成功基準も異なります。

スキルを作成する前に確認すること

以下のテストを適用して、スキルが本当の価値を提供することを確かめてください。

知識の差分テスト

• これは専門家が習得するのに何年もかかる知識をまとめていますか？ 基本事項や標準ライブラリの使い方を説明しているなら、重複した内容です。
• Claude に説明しているのでしょうか、それとも Claude に力を与えているのでしょうか？ スキルは概念を教えるのではなく、エージェントに専門知識を与えるものであるべきです。
• すべての段落はコンテキストを使う価値がありますか？ システムプロンプト、会話履歴、その他のスキルと共有するため、トークンの効率が重要です。

起動の費用対効果

• 説明には WHAT、WHEN、キーワードが含まれていますか？ 曖昧な説明ではスキルが起動されません。
• 説明だけを読んだエージェントは、いつ使うべきかを正確に理解できますか？ 不明瞭なら、そのスキルは認識されません。

自由度の調整

• エージェントが間違えた場合、何が起きますか？ 重大な結果を招く場合は自由度を低く（正確なスクリプト）、影響が小さい場合は自由度を高く（原則）します。
• 正しい方法は 1 つですか、それとも有効な方法が複数ありますか？ 方法が 1 つなら規範的に、複数あるなら例を交えたガイダンスにします。

トークン効率

• 専門知識を損なわずに圧縮できますか？ 必要に応じて読み込むリファレンスを使えば、コンテキストを節約できます。
• スクリプト化できる、繰り返しの多い手順はありますか？ 再利用可能なコードは、指示に繰り返し記載せず scripts/ に置いてください。

使用方法

このスキルは、コンテキストの使用量を最小限に抑えるために、段階的な開示を採用しています。

1. ワークフローから始める（SKILL.md）

スキルの作成またはリファクタリングには、以下の 4 ステップのワークフローに従ってください。

2. 実装の詳細を参照する（AGENTS.md）

ファイルシステムの規約、命名パターン、構造上のルールについては、AGENTS.md を読み込んでください。

3. 必要に応じて特定のリファレンスを読み込む

以下のワークフローの各ステップには、読み込むリファレンスファイルが記載されています。現在のステップに必要なものだけを読み込んでください。

• ディレクトリ構造 → references/file-system.md
• description フィールドの規則 → references/skill.md
• AGENTS.md のパターン → references/agents.md
• 段階的開示のルール → references/progressive-disclosure.md
• リファレンスファイルの形式 → references/references.md
• スクリプトの規則 → references/scripts.md
• アセットのガイドライン → references/assets.md
• CHANGELOG のメンテナンス → references/changelog.md

すべてのリファレンスを一度に読み込まないでください — 現在のステップに関連するものだけを読み込んでください。

どのワークフローに従うべきですか？

タスクに応じて選択してください。

• スキルを一から作成する → スキル作成ワークフロー（ステップ 1〜4）に従います
• 既存のスキルを改善する → ステップ 4（スキルを編集する）に進みます
• スキルの品質を監査する → スキル監査ワークフローに従います

スキル作成ワークフロー

スキルを作成またはリファクタリングするには、該当しない明確な理由がある場合にのみステップを省略し、「スキル作成ワークフロー」の順序に従ってください。

進捗を管理するため、このチェックリストをコピーしてください：

- [ ] Step 1: Understanding - Gather concrete examples of skill usage
- [ ] Step 2: Planning - Identify reusable scripts, references, assets
- [ ] Step 3: Initializing - Check existing skills, create directory structure
- [ ] Step 4: Editing - Write agent-focused content with procedural knowledge and update CHANGELOG

適用するこのスキルのルールと、その理由を要約に記載してください。

ステップ 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合にのみ、このステップを省略してください。既存のスキルに取り組む場合でも、このステップは役立ちます。

効果的なスキルを作成するには、スキルがどのように使われるかを具体例で明確に理解してください。この理解は、ユーザーから直接提供された例、または生成後にユーザーのフィードバックで検証した例から得られます。

例：画像編集スキルを作成する場合は、次のように尋ねます。

• 「どのような機能が必要ですか？編集、回転、その他ですか？」
• 「使用例はありますか？」
• 「『赤目を除去』『画像を回転』などのトリガーフレーズはほかにもありますか？」

まず、具体的な質問を 2〜3 個（機能、例、トリガーフレーズについて）尋ね、最初に質問をまとめて投げかけるのではなく、回答に基づいて追加で質問してください。

スキルがサポートすべき機能を明確に把握できたら、このステップを終了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするには、それぞれの例について次の点を分析します。

1. 最初から例をどのように実行するかを検討する
2. これらのワークフローを繰り返し実行するときに役立つスクリプト、リファレンス、アセットを特定する

例：

• 「この PDF を回転して」に対応する pdf-editor スキル → 毎回コードを書き直さずに済むよう、scripts/rotate-pdf.sh を保存する
• 「ToDo アプリを作成して」に対応する frontend-app-builder → ボイラープレートのテンプレートとして assets/hello-world/ を保存する
• 「今日ログインしたユーザー数は？」に対応する big-query → テーブルスキーマを記載した references/schema.md を保存する

それぞれの具体例を分析し、再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成します。

ステップ 3：スキルを初期化する

必須：ディレクトリ構造を作成する前に、references/file-system.md を読み込んでください。

新しいスキルの場合： assets/skill-template/ のテンプレートをコピーし、カスタマイズして使用してください。

リファクタリング対象の既存スキルの場合： ステップ 4 に進んでください — スキルはすでに存在します。

作成する前に、重複する既存のスキルがないか確認してください。

ls -la .claude/skills 2>/dev/null || echo "No project skills found"
ls -la ~/.claude/skills 2>/dev/null || echo "No global skills found"

関連するスキルが見つかった場合は、簡潔に伝えてください。「[リスト] が見つかりました — これらを含めるか、統合しますか？」

ディレクトリ構造と命名については、AGENTS.md およびリファレンスファイルの規則に従ってください。

ステップ 4：スキルを編集する

必須：references/skill.md を読み込み、description フィールドの慣例と frontmatter のルールを確認してください。

（新規作成または既存の）スキルを編集する際は、そのスキルが別のエージェントインスタンスによって利用されることを念頭に置いてください。エージェントにとって有益で、かつ自明ではない情報を含めることに重点を置きます。別のエージェントインスタンスがタスクをより効果的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

タスクの壊れやすさに応じて裁量を調整します：

タスクの種類	裁量の度合い	ガイダンスの形式	例
クリエイティブ／デザイン	高い裁量	原則、思考パターン、アンチパターン	「大胆な美的表現を貫く」
コードレビュー	中程度の裁量	例を含むガイドライン、判断の枠組み	「優先順位：セキュリティ ＞ ロジック ＞ パフォーマンス」
ファイル操作	低い裁量	正確なスクリプト、具体的な手順、変更不可	「正確なコマンドを使用：pandoc --flag」

判断の基準：「エージェントが間違えた場合、どのような結果になりますか？」

• 影響が大きい（ファイルの破損、データの損失）→ 低い裁量で、正確なスクリプトを用いる
• 影響が中程度（最適でないコード、スタイル上の問題）→ 中程度の裁量で、例を示す
• 影響が小さい（美的な選択、複数の妥当な方法）→ 高い裁量で、原則を示す

既存のスキルを更新する場合、大規模な構造変更や整合性の確保には assets/skill-template/ のテンプレートを参考にできます。一貫性は不可欠なため、適合させるために積極的な再フォーマットを推奨します。

既存のスキルを更新する場合は、frontmatter の metadata.version の値を引き上げてください。変更の範囲が大きい場合はメジャー変更（1.0 から 2.0）、それ以外の場合はマイナー変更（1.0 から 1.1）とします。

バージョン管理：

• メジャー（1.0 → 2.0）： 大幅な書き換え、破壊的変更、全面的な再構成
• マイナー（1.0 → 1.1）： 新しいセクション、重要な追加、改善
• パッチ（1.0.0 → 1.0.1）： バグ修正、誤字の訂正（3 桁目は任意）

CHANGELOG のメンテナンス： スキルを更新した後、「Keep a Changelog」形式で CHANGELOG.md を更新または作成してください。

# Changelog

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features/capabilities with rationale

### Changed
- Modifications with why (always include rationale)

### Fixed
- Bug fixes with explanation

### Version
- Version bump note

変更内容とその理由を記録してください。理由は、今後のメンテナーにとって重要です。テストによる改善の場合は、評価結果へのリンクを記載してください。CHANGELOG のバージョンは frontmatter の metadata.version と一致させてください。

スキル監査ワークフロー

既存のスキルを監査またはレビューする場合（ゼロから作成する場合を除く）は、次の構造化された手順に従ってください。

1. Frontmatter の監査

各フィールドが要件を満たしているか確認します。

• name：小文字、ハイフンのみ、64 文字以下で、ディレクトリ名と一致している
• description：「Use when」で始まり、WHAT／WHEN／KEYWORDS を含み、具体的なトリガーフレーズがある
• license：記載されている（任意ですが、推奨）
• metadata.version：記載され、意味のある値で、CHANGELOG.md の最新バージョンと一致している

2. 構成の監査

想定されるセクションと照合します：Never Do、Before [Action] Ask、How to Use、Main Workflow。不足しているセクションを記録してください。

3. CHANGELOG とバージョンの監査

CHANGELOG.md の有無と内容を確認します。

• CHANGELOG がない： ドキュメントが欠落していることを指摘する
• バージョンの不一致： CHANGELOG の最新バージョンが frontmatter の metadata.version と一致しているか確認する
• 理由の記載がない： 変更には WHAT だけでなく WHY も記載されているか確認する
• 形式への準拠： 「Keep a Changelog」の正しい構成になっているか確認する
• 空のセクション： Added／Changed／Fixed セクションに意味のある内容があるか確認する

4. 知識差分テスト

各コンテンツブロックについて、次のように確認します：「Claude はすでにこれを知っていますか？」冗長または専門家向けとして分類します。冗長なコンテンツの割合を計算してください。50％を超える場合は、大幅な改訂を推奨してください。

5. 実行可能な成果物の作成

• 具体的な改善案を優先度順に提示する
• 批判だけでなく、改善後の具体的な description を含める
• 監査レポートとともに、改善後の SKILL.md を提示する