enhance-skills

enhance-skills

スキル定義のトリガー品質、構造、見つけやすさを分析します。

ワークフロー

1. 検出 - すべての SKILL.md ファイルを検索します
2. 解析 - フロントマターとコンテンツを抽出します
3. チェック - 以下のナレッジに基づいてすべてのパターンチェックを実行します
4. フィルタリング - 確実性によるフィルタリングを適用します
5. レポート - Markdown の出力を生成します
6. 修正 - --fix フラグが指定されている場合、自動修正を適用します

---

スキルのナレッジリファレンス

フロントマターのフィールド（完全なリファレンス）

フィールド	必須	説明	検証
name	いいえ	表示名。指定がない場合はディレクトリ名が使用されます	小文字、最大 64 文字
description	推奨	スキルの機能と使用するタイミング	最大 1024 文字。トリガーを含める必要があります
argument-hint	いいえ	オートコンプリート用のヒント。例：[file-path]	30 文字未満
disable-model-invocation	いいえ	true = 手動のみ（副作用がある場合）	ブール値。デフォルトは false
user-invocable	いいえ	false = / メニューに表示されない（自動のみ）	ブール値。デフォルトは true
allowed-tools	いいえ	Claude が許可なしで使用できるツール	カンマ区切りのリスト
model	いいえ	スキルの有効時に使用する特定のモデル	opus、sonnet、haiku
context	いいえ	fork = 分離されたサブエージェントのコンテキストで実行	fork または省略
agent	いいえ	実行に使用するサブエージェントの種類	Explore、Plan、general-purpose
hooks	いいえ	スキルに適用されるライフサイクルフック	PreToolUse、PostToolUse

ディレクトリ構造

skills/my-skill/
├── SKILL.md           # Required - core definition (under 500 lines)
├── reference.md       # Optional - detailed documentation
├── examples.md        # Optional - usage examples
└── scripts/           # Optional - helper scripts
    └── helper.py

保存場所：

• エンタープライズ：管理対象の設定
• 個人：~/.claude/skills/<name>/SKILL.md
• プロジェクト：.claude/skills/<name>/SKILL.md

呼び出し制御のパターン

手動のみ（副作用があるスキル向け）：

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

バックグラウンドナレッジ（自動のみ、メニューには非表示）：

---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---

フルアクセス（デフォルト - 自動と手動の両方）：

---
name: review
description: Use when user asks to review code. Checks quality and security.
---

トリガーフレーズ

自動検出できるよう、description にはトリガーのコンテキストを含めてください：

• 「ユーザーが…を依頼したときに使用」
• 「…の場合に使用」
• 「…の場合に呼び出す」

良い例： "ユーザーが「コードをレビュー」「PR をチェック」「コードレビュー」を依頼したときに使用" 悪い例： "コードをレビューします"（トリガーのコンテキストがありません）

動的コンテキストの挿入

スキルでは、バッククォート構文を使って動的なコンテンツを挿入できます：

---
name: pr-summary
description: Summarize PR changes
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

ルール：

• ! の後にバッククォートで囲んだコマンドを指定します
• 1 つのスキルにつき挿入は 3 回までにします
• 挿入するたびにコンテキストの予算が増加します

文字列置換

変数	説明
$ARGUMENTS	呼び出し時に渡されるすべての引数
${CLAUDE_SESSION_ID}	現在のセッション ID

コンテキスト予算

• スキルの説明のデフォルト上限は約 15,000 文字です
• 上限を超えたコンテンツは切り捨てられます
• /context コマンドで確認できます
• 次の設定で上限を増やせます：SLASH_COMMAND_TOOL_CHAR_BUDGET=30000

サブエージェントの実行

context: fork を使用する場合：

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

エージェントの種類：

エージェント	用途	ツールへのアクセス
Explore	読み取り専用のコードベース探索	Read、Grep、Glob のみ
Plan	計画に特化した推論	Read、分析ツール
general-purpose	すべての機能	すべてのツール

スキルに適用されるフック

---
name: secure-operations
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

ツールの制限

セキュリティのため、スコープを限定したツールパターンを使用します：

パターン	意味
Bash(git:*)	git コマンドのみ
Bash(npm:*)	npm コマンドのみ
Bash(gh:*)	GitHub CLI のみ
Read(src/**)	src/ 内のファイルのみ

---

検出パターン

1. フロントマターの検証（確実性：高）

必須：

• --- 区切り文字を使った YAML フロントマター
• name フィールド（小文字、最大 64 文字）
• description フィールド（最大 1024 文字）

推奨：

• 追跡用の version フィールド
• 入力を受け取るスキル向けの argument-hint
• セキュリティ用の allowed-tools
• 特定のモデルが必要な場合の model

報告対象：

• フロントマターの区切り文字がない
• フィールド値が無効（name に大文字が含まれる、description が 1024 文字を超える）

2. トリガーの品質（確実性: 高）

チェック: 説明にトリガーフレーズが含まれていること トリガーパターン: 「Use when」、「Invoke when」、「Use when user asks」

指摘対象:

• トリガーのコンテキストがない説明
• 「Useful tool」や「Does stuff」のような曖昧な説明

3. 呼び出し制御（確実性: 高）

チェック: 副作用のあるスキルが保護されていること

指摘対象:

• 名前に deploy/ship/publish を含むが disable-model-invocation が設定されていないスキル
• 危険な自動呼び出し可能スキル（誤ってトリガーされる可能性がある）

4. ツールの制限（確実性: 高）

チェック: ツールが適切にスコープ設定されていること

指摘対象:

• 制限のない Bash（Bash(git:*) などであるべき）
• 読み取り専用スキルに Write/Edit がある
• 調査スキルに Task ツールがある

5. コンテンツの範囲（確実性: 中）

ガイドライン:

• SKILL.md は 500 行未満
• 大きなコンテンツは references/ サブディレクトリに配置
• 動的注入は最大 3 つ

指摘対象:

• 500 行を超える SKILL.md
• 3 つを超える !バッククォート`` 注入
• 埋め込まれた大きな例（examples.md に移動）

6. 構造の品質（確実性: 中）

推奨セクション:

• 目的/概要
• 必須チェックまたはワークフローの手順
• 出力形式
• 例（複雑な場合）

7. コンテキスト設定（確実性: 中）

チェック: コンテキスト設定が適切であること

指摘対象:

• agent タイプなしの context: fork
• context: fork なしの agent タイプ
• エージェントタイプと allowed-tools の不一致

8. アンチパターン（確実性: 低）

• 具体的なトリガーのない曖昧な説明
• 責務が多すぎる（複数のスキルに分割すべき）
• 明確に入力が必要なスキルに argument-hint がない
• 冗長な chain-of-thought 指示（現代のモデルに「think step by step」は不要）

---

自動修正の実装

1. frontmatter の欠落

---
name: skill-name
description: "Use when..."
version: 4.2.0
---

2. トリガーフレーズの欠落

説明に「Use when user asks...」というプレフィックスを追加

3. 制限のない Bash

Bash を Bash(git:*) または適切なスコープに置き換え

---

出力形式

## Skill Analysis: {skill-name}

**File**: {path}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Frontmatter Issues ({n})
| Issue | Fix | Certainty |

### Trigger Issues ({n})
| Issue | Fix | Certainty |

### Invocation Issues ({n})
| Issue | Fix | Certainty |

### Tool Issues ({n})
| Issue | Fix | Certainty |

### Scope Issues ({n})
| Issue | Fix | Certainty |

---

パターン統計

カテゴリ	パターン数	自動修正可能
Frontmatter	5	2
トリガー	2	1
呼び出し	3	1
ツール	3	1
範囲	3	0
構造	2	0
コンテキスト	3	0
アンチパターン	4	0
合計	25	5

---

### 例: トリガーフレーズの欠落

<bad_example>

name: code-review
description: "Reviews code for issues"

なぜ悪いか: 自動検出のためのトリガーコンテキストがありません。 </bad_example>

<good_example>

name: code-review
description: "Use when user asks to 'review code', 'check this PR'. Reviews code for issues."

なぜ良いか: 明確なトリガーフレーズが自動検出を可能にします。 </good_example>

例: 危険な自動呼び出し

<bad_example>

name: deploy
description: "Deploys code to production"

なぜ悪いか: 副作用のあるスキルが誤って自動呼び出しされる可能性があります。 </bad_example>

<good_example>

name: deploy
description: "Deploy to production environment"
disable-model-invocation: true

なぜ良いか: 手動のみにすることで誤ったデプロイを防ぎます。 </good_example>

例: 制限のないツール

<bad_example>

name: git-helper
allowed-tools: Bash

なぜ悪いか: 制限のない Bash はあらゆるコマンドを許可します。 </bad_example>

<good_example>

name: git-helper
allowed-tools: Bash(git:*)

なぜ良いか: git コマンドのみにスコープ設定されています。 </good_example>

例: 大きすぎるスキル

<bad_example>

# Complex Analysis
[800 lines of detailed instructions]

なぜ悪いか: 大きなスキルはコンテキストの予算を消費します（15K 文字の制限）。 </bad_example>

<good_example>

# Complex Analysis
Core instructions here (under 500 lines).
For details, see `references/detailed-guide.md`.

なぜ良いか: コアスキルは簡潔で、詳細は別ファイルにあります。 </good_example>

例: コンテキスト/エージェントの不一致

<bad_example>

name: researcher
context: fork
# Missing agent type

なぜ悪いか: エージェントタイプを指定せずに fork コンテキストを使用しています。 </bad_example>

<good_example>

name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob

なぜ良いか: エージェントタイプが許可されたツールと一致しています（Explore = 読み取り専用）。 </good_example>

---

制約

• 自動修正は確実性の高い問題にのみ適用する
• トリガーの品質を評価する際はスキルのコンテキストを考慮する
• コンテンツを削除せず、改善のみを提案する
• 上記の埋め込みナレッジリファレンスに対して検証する