skill-structure

スキルの構造

コマンドとスキルの統合

カスタムスラッシュコマンドとスキルは同じものです。.claude/commands/review.md のファイルも、.claude/skills/review/SKILL.md のスキルも、どちらも /review を作成します。既存の .claude/commands/ ファイルも引き続き動作します。スキルでは、補助ファイル用のディレクトリ、呼び出しを制御するフロントマター、コンテキストの自動読み込みが追加されます。

スキルとコマンドの名前が同じ場合は、スキルが優先されます。

どちらを使うか：

種類	使用する場面
コマンドファイル（commands/name.md）	補助ファイルを必要としない、単純な単一ファイルのワークフロー
スキルディレクトリ（skills/name/SKILL.md）	参照資料、背景知識、または段階的な開示が必要な場合

命名規則

規則	例
形式	kebab-case、小文字、1～64 文字
パターン	^[a-z][a-z0-9]*(-[a-z0-9]+)*$
一致させるもの	ディレクトリ名と完全に一致

良い例／悪い例：

良い例	悪い例	理由
stimulus-coder	MySkill	大文字は使用できません
tdd-workflow	skill_helper	アンダースコアは使用できません
pdf-processing	-invalid	ハイフンで始めることはできません
seo-content	skill--bad	ハイフンを連続して使用できません

ディレクトリ構造

フラット構造（ほとんどのスキル）

plugins/majestic-rails/skills/stimulus-coder/SKILL.md
-> name: stimulus-coder
-> invoked as: Skill("stimulus-coder")

入れ子構造（カテゴリ別のスキル）

plugins/majestic-rails/skills/dhh-coder/SKILL.md
-> name: dhh-coder
-> invoked as: Skill("dhh-coder")

要点：

• name フィールドに指定するのはスキル名のみです（フルパスではありません）
• ディレクトリ名は name と完全に一致させる必要があります
• 関連するスキルをグループ化するには、入れ子構造を使用します（ceo/, fundraising/, research/）

段階的な開示

複雑なスキルは、複数のファイルに分割します。

my-skill/
+-- SKILL.md (overview, <500 lines)
+-- references/
|   +-- patterns.md (detailed patterns)
|   +-- examples.md (extended examples)
+-- scripts/
    +-- helper.py (utility scripts)

規則：

• 参照資料は1階層のみです（SKILL.md から reference.md を参照し、それ以上深くしないでください）
• スクリプトはコンテキストに読み込まずに実行されます
• SKILL.md はナビゲーションと主要な内容に焦点を絞ります
• サブディレクトリは scripts/、references/、assets/ のみです

フロントマター

基本フィールド

---
name: skill-name              # Matches directory, defaults to dir name if omitted
description: What it does...  # Recommended, max 1024 chars
allowed-tools: Read Bash      # Optional, space-delimited
---

全フィールドのリファレンス

フィールド	必須	説明
name	いいえ	小文字、数字、ハイフン（最大64文字）。デフォルトはディレクトリ名です。
description	推奨	機能と使用する場面を記述します。最大1024文字です。
argument-hint	いいえ	オートコンプリート時に表示するヒントです。例：[issue-number]
disable-model-invocation	いいえ	true = Claude による自動読み込みを禁止します。手動ワークフロー向けです。デフォルト：false
user-invocable	いいえ	false = / メニューに表示しません。背景知識向けです。デフォルト：true
allowed-tools	いいえ	権限確認なしで使用できるツールです。例：Read, Bash(git *)
model	いいえ	haiku、sonnet、または opus
context	いいえ	隔離されたサブエージェントのコンテキストで実行するには fork を指定します
agent	いいえ	context: fork のときのサブエージェントの種類です。Explore、Plan、general-purpose、またはカスタムを指定します

説明のテンプレート

[What it does]. Use when [trigger contexts]. Triggers on [specific keywords].

規則：

• 最大1024文字
• 三人称で記述します（「I process...」ではなく「Processes...」）
• ユーザーが自然に使うトリガーキーワードを含めます

呼び出しの制御

フロントマター	ユーザーが呼び出せる	Claude が呼び出せる	読み込み時
（デフォルト）	はい	はい	説明は常にコンテキストに含まれ、呼び出し時に全文が読み込まれます
user-invocable: false	いいえ	はい	説明は常にコンテキストに含まれ、関連する場合に読み込まれます

判断ガイド：

• 背景知識（規約、ドメインコンテキスト） -> user-invocable: false
• その他すべて -> デフォルト（ユーザーとモデルの両方が呼び出せます）

注： disable-model-invocation: true の使用は避けてください。副作用のあるコマンド／スキルは、モデルによる呼び出しを完全に禁止するのではなく、確認手順（AskUserQuestion）を使用してください。

動的機能

引数

ユーザー入力には $ARGUMENTS を使用します。コンテンツ内に記載されていない場合、引数は自動的に末尾に追加されます。

---
name: fix-issue
---
Fix GitHub issue $ARGUMENTS following our coding standards.

個別の引数：$ARGUMENTS[0] または省略形の $0、$1、$2。

動的コンテキスト注入

!`command` 構文を使うと、コンテンツが Claude に渡される前にシェルコマンドが実行されます。

## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`

コマンドは直ちに実行され、プレースホルダーは出力に置き換えられます。

サブエージェントの実行

context: fork を追加すると、会話履歴なしで独立して実行できます。

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...

ツールへのアクセス

必要なツール	使用例
Read, Grep, Glob	コードベース内のパターンを検索
Bash(git *)	Git 操作のみ
Bash(gh *)	GitHub CLI 操作
WebFetch	外部ドキュメントを取得
なし	純粋な知識やガイダンス

制限事項

• SKILL.md： 最大 500 行
• 名前： 最大 64 文字
• 説明： 最大 1024 文字

検証チェックリスト

• 名前がディレクトリ名と完全に一致している
• 名前がパターン ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ に準拠している
• 説明が 1024 文字未満で、トリガーキーワードを含んでいる
• 標準的な Markdown 見出しを使用している（XML タグではない）
• SKILL.md が 500 行未満である
• スキルに副作用がある場合、確認に AskUserQuestion を使用している
• 特定のツールが必要な場合、allowed-tools が設定されている
• ペルソナに関する記述や帰属表示がない
• サブディレクトリが scripts/、references/、assets/ のみである
• 実際の使用環境でテスト済みである