Skill Creator

エージェントスキル作成標準

優先度：P0（重大）

高密度のエージェントスキルを作成するための厳格なガイドラインです。段階的な開示と戦略的なコンテンツ構成により、トークン消費を最小限に抑えながら情報密度を最大化します。

基本原則

まずトークン効率を重視 ⚡

すべての単語にトークンコストがかかります。情報量とトークン数の比率が最大になるようスキルを設計します。

• 段階的な読み込み：最初は必須コンテンツのみを読み込みます
• 遅延参照：詳細な例は references/ フォルダーに移します
• 命令形で圧縮：動詞、略語、箇条書きを使用します
• コンテキストウィンドウを考慮：エージェントごとに 4k～32k トークンの上限に合わせて設計します

3 段階の読み込みシステム

Level 1: Metadata (100 words) → Always loaded
Level 2: SKILL.md Body (100 lines) → When triggered
Level 3: References/Scripts/Assets → As needed

ディレクトリー構成

skills/
└── {category}/                     # e.g., "flutter" (lowercase)
    └── {skill-name}/               # e.g., "bloc-state-management" (kebab-case)
        ├── SKILL.md                # Core Logic (High Density, <100 lines)
        ├── scripts/                # Executable code (Deterministic tasks)
        │   └── automation.py
        ├── references/             # Heavy Examples (Lazy loaded)
        │   ├── patterns.md
        │   └── examples.md
        └── assets/                 # Output templates (Never loaded)
            └── template.json

作成ルール（トークン最適化）

1. 命令形で圧縮：動詞で始めます。「Please／You should」は使いません。

   • 冗長：「状態管理には BLoC を使用するべきです。」（8 語）
   • 効率的：「状態管理には BLoC を使用します。」（5 語）

2. トークン効率：情報量とトークン数の比率を最大化します。

   • 読みやすさを損なわない範囲で冠詞（「the」「a」）を省きます
   • 標準的な略語（cfg、param、impl）を使用します
   • 段落より箇条書きを使います（密度 3 倍）

3. 段階的な開示：必須情報を先に示し、詳細は必要に応じて提示します。

   • 基本的なワークフローは SKILL.md に記載します
   • 複雑な例は references/ に記載します
   • テンプレートとアセットは読み込みません

4. コンテキストを考慮した設計：エージェントごとに上限が異なります。

   • Cursor：約 100k トークン
   • Claude：約 200k トークン
   • Windsurf：約 32k トークン

コンテンツのセクション（トークン予算あり）

SKILL.md に必要なセクション：

1. フロントマター（必須）：トリガー用のメタデータ（最大 100 語）

   ---
   name: Skill Name
   description: What it does + when to use it (triggers activation)
   metadata:
     labels: [tag1, tag2]
     triggers:
       files: ['**/*.ext']
       keywords: [term1, term2]
   ---
   

2. 優先度：P0（重大）、P1（標準）、または P2（任意）

3. 構成：想定されるファイル構成を ASCII ツリーで示します

4. ガイドライン：「実施すること」を箇条書きにします（命令形）

5. アンチパターン：「実施しないこと」を箇条書きにします

6. 参照リンク：references/ 内のファイルへのリンク（遅延読み込み）

サイズ制限（厳守）

要素	制限	超過した場合の対応
SKILL.md 全体	100 行	references/ に移動
インラインコードブロック	10 行	references/ に移動
アンチパターンの項目	15 語	命令形で圧縮
優先度の後の説明	0 行	削除（フロントマターを使用）
表	8 行	references/ に移動
説明セクション	10 行	references/ に移動

リソースの整理（トークン節約）

scripts/ - 実行可能なコード

使用する場合：決定論的で、繰り返し行うタスク 利点：コンテキストに読み込まれず、直接実行されます 例：コードジェネレーター、フォーマッター、バリデーター

references/ - ドキュメント

使用する場合：詳細な例、API ドキュメント、複雑なパターン 利点：必要なときだけ読み込まれるため、SKILL.md を簡潔に保てます 例：実装パターン、エラー処理ガイド

assets/ - 出力テンプレート

使用する場合：ひな形ファイル、画像、設定 利点：読み込まれず、必要に応じて出力にコピーされます 例：プロジェクトテンプレート、設定ファイル、アイコン

スキル作成のライフサイクル

フェーズ 1：理解（トークン監査）

1. 具体的なユースケースを定義します
2. 繰り返し現れるパターンを特定します
3. エージェントごとのトークン予算を算出します

フェーズ 2：計画（リソース戦略）

1. 基本的なワークフロー → SKILL.md
2. 複雑な例 → references/
3. 繰り返し使用するコード → scripts/
4. テンプレート → assets/

フェーズ 3：実装（圧縮）

1. 命令形のガイドラインを記述します
2. 例を要点に絞って圧縮します
3. コンテキストウィンドウに収まるか確認します

フェーズ 4：検証（トークンテスト）

1. 読み込み効率を検証します
2. 異なるエージェントでテストします
3. トークン消費量を測定します

検証チェックリスト

最終確認の前に、次の点を確認してください。

• SKILL.md が100行以下（理想は40～60行）
• 10行を超えるインラインコードがない
• frontmatter の内容が重複していない
• アンチパターンが厳密な形式に従っている（下記参照）
• 複雑な例は references/ に配置されている
• 8行を超える表は references/ に移されている
• Priority の後に説明の重複がない

アンチパターン（トークンの浪費）

• 冗長な説明：「これは重要です。なぜなら……」→ 削除します
• 冗長なコンテキスト：同じ情報が複数箇所にある
• 大きなインラインコード：10行を超えるコードは references/ に移します
• 会話調の文体：「方法を見てみましょう……」→「これを実行します：」
• 過剰な設計：単純なスキルに複雑な構成を使う
• 冗長な説明：frontmatter の description を ## Priority の後に繰り返さない
• 大きすぎるスキル：SKILL.md が100行を超える場合は references/ に抽出します
• 書式の入れ子：**太字**: \さらに太字`` は避けます。視覚的なノイズが生じます
• 冗長なアンチパターン：下記の厳密な形式を参照してください

アンチパターンの形式（厳守）

形式：**X をしない**: Z ではなく Y を実行します。[任意の補足。合計15語以内]

例：

❌ Verbose (24 words):

- **No Manual Emit**: `**Avoid .then()**: Do not call emit() inside Future.then; always use await or emit.forEach.`

✅ Compressed (11 words):

- **No .then()**: Use `await` or `emit.forEach()` to emit states.

❌ Verbose (18 words):

- **No UI Logic**: `**Logic in Builder**: Do not perform calculations or data formatting inside BlocBuilder.`

✅ Compressed (9 words):

- **No Logic in Builder**: Perform calculations in BLoC, not UI.

段階的な開示のチェックリスト

次の場合は references/ に抽出します。

• 10行を超えるコード例
• 8行を超える表
• 10行を超える説明セクション
• 複数のコード形式や代替案
• 詳細なパフォーマンスベンチマーク
• 手順ごとのチュートリアル

リファレンスと例

以下の拡張テンプレートを使って、新しいスキルを作成します。 references/TEMPLATE.md

ライフサイクル全般のガイダンスについては、次を参照してください。 references/lifecycle.md

リソースの整理パターンについては、次を参照してください。 references/resource-organization.md