skill-creator

スキル作成ガイド

このガイドでは、Agent Skills 仕様に従って、Apollo GraphQL および GraphQL 開発に効果的なスキルを作成する方法を説明します。

スキルとは？

スキルとは、専門知識、ワークフロー、またはツール連携によって AI エージェントの機能を拡張する指示を含むディレクトリです。エージェントが関連するタスクを検出すると、スキルが自動的に有効になります。

ディレクトリ構成

スキルには、最低限 SKILL.md ファイルが必要です。

skill-name/
├── SKILL.md              # Required - main instructions
├── references/           # Optional - detailed documentation
│   ├── topic-a.md
│   └── topic-b.md
├── scripts/              # Optional - executable helpers
│   └── validate.sh
├── templates/            # Optional - config/code templates
│   └── config.yaml
└── assets/               # Optional - static resources (images, schemas, data files)

SKILL.md の形式

フロントマター（必須）

---
name: skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger conditions: (1) first condition, (2) second condition.
license: MIT
compatibility: Works with Claude Code and similar AI coding assistants.
metadata:
  author: your-org
  version: "1.0.0"
allowed-tools: Read Write Edit Glob Grep
---

フロントマターのフィールド

フィールド	必須	説明
name	はい	小文字とハイフンのみを使用します。ディレクトリ名と一致させる必要があります。最大 64 文字です。
description	はい	スキルの機能と使用するタイミングを記述します。最大 1024 文字です。
license	いいえ	ライセンス名（例：MIT、Apache-2.0）。
compatibility	いいえ	環境要件。最大 500 文字です。
metadata	いいえ	作成者、バージョンなどのキーと値のペア。
allowed-tools	いいえ	事前承認済みツールをスペース区切りで列挙します。Bash(curl:*) は含めないでください。

名前のルール

• 小文字、数字、ハイフンのみを使用します
• ハイフンで始めたり終えたりしないでください
• ハイフンを連続して使用しないでください（--）
• 親ディレクトリ名と一致させる必要があります

適切な例：apollo-client、graphql-schema、rover 不適切な例：Apollo-Client、-apollo、apollo--client

説明のベストプラクティス

エージェントがスキルを有効にするタイミングを特定できるような説明を記述します。

# Good - specific triggers and use cases
description: >
  Guide for designing GraphQL schemas following industry best practices. Use this skill when:
  (1) designing a new GraphQL schema or API,
  (2) reviewing existing schema for improvements,
  (3) deciding on type structures or nullability,
  (4) implementing pagination or error patterns.

# Bad - vague and unhelpful
description: Helps with GraphQL stuff.

本文の内容

Markdown 本文には、エージェントが従う指示を記述します。分かりやすい構成にしてください。

推奨セクション

1. 概要 - スキルの目的を簡潔に説明します
2. プロセス - 手順ごとのワークフロー（複数手順の場合はチェックボックスを使用します）
3. クイックリファレンス - 一般的なパターンと構文
4. セキュリティ - スキルがセキュリティ上の影響を受ける内容を扱う場合のリスク、緩和策、検証
5. 参考ファイル - 詳細なドキュメントへのリンク
6. 重要なルール - トピックごとにまとめた重要なガイドライン
7. 基本ルール - 必ず守るべきことと、してはいけないこと

構成例

# Skill Title

Brief overview of what this skill helps with.

## Process

Follow this process when working on [task]:

- [ ] Step 1: Research and understand requirements
- [ ] Step 2: Implement the solution
- [ ] Step 3: Validate the result

## Quick Reference

### Common Pattern

\`\`\`graphql
type Example {
  id: ID!
  name: String
}
\`\`\`

## Security

> **Risk: [brief description of what can go wrong].**
> [What the user MUST do to prevent it.]

- ALWAYS [secure default behavior]
- NEVER [dangerous configuration] in production

## Reference Files

- [Topic A](references/topic-a.md) - Detailed guide for topic A
- [Topic B](references/topic-b.md) - Detailed guide for topic B

## Key Rules

### Category One

- Rule about this category
- Another rule

### Category Two

- Rule about this category

## Ground Rules

- ALWAYS do this important thing
- NEVER do this problematic thing
- PREFER this approach over that approach

セキュリティ上重要な内容

スキルが、誤用するとセキュリティ上の問題を引き起こす可能性がある設定、コード、またはガイダンスを生成する場合、スキルはそのリスクを明示し、LLM に分かるように示す必要があります。LLM は文脈だけからセキュリティへの影響を推測できません。そのため、明確にラベル付けされた情報が必要です。

スキルにセキュリティガイダンスが必要なのはどのような場合ですか？

以下のいずれかに当てはまる場合、そのスキルはセキュリティ上重要です。

• データへのアクセスを制御する設定（キャッシュ、認証、CORS、権限）を生成する
• シークレット、認証情報、またはトークンを扱う
• 高い権限で実行されるコードを生成する
• 共有、公開、またはユーザーへの公開対象となるデータを制御する
• ネットワークのバインド、エンドポイント、または外部アクセスを設定する

スキルでセキュリティを明示する方法

1. SKILL.md または参考ファイルに、## Security というラベルを付けた専用のセキュリティセクションを設けます。「Private data」や「Customization」ではなく、「Security」という語を使ってください。LLM が該当カテゴリを認識できるようにするためです。

2. リスクが生じる箇所に明示的な警告を配置します。リスクを生み出す設定やコードの近くにセキュリティガイダンスを記載し、LLM が読み込まない可能性のある別ファイルには置かないでください。

   ### Response caching scope
   
   > **Security: data leakage risk.** All cached data is PUBLIC by default.
   > User-specific fields MUST use `scope: PRIVATE` with a `private_id`
   > configured, or they will be shared across all users.
   

3. 検証チェックリストの項目 — セキュリティ上重要な機能ごとに、対応する検証項目を設ける必要があります。これらは ## Security 見出しの下にまとめてください。

4. 基本ルール — セキュリティ上重要な動作について、必ず守る／絶対にしてはいけないというルールを追加します。これらは LLM に対する最も強いシグナルです。

5. データモデルを必ず確認する — 正しいセキュリティ設定がユーザーのデータモデル（たとえば、どのフィールドがユーザー固有か）の理解に依存する場合、設定を生成する前にユーザーに確認するようスキルで LLM に指示する必要があります。LLM に推測させないでください。

アンチパターン

• 「デフォルトで公開」のようなセキュリティ上重要なデフォルト設定について、セキュリティ上の懸念であることを明示せずに説明する
• セキュリティガイダンスを、必要に応じて読み込まれる参照ファイルだけに記載する — 重要な警告は SKILL.md 自体に含める必要があります
• 必須のセキュリティ要件に「検討してもよいでしょう」のような曖昧な表現を使う — 「必ず実行する」と「絶対に行わない」を使います
• スキーマのどのフィールドが非公開かを LLM が理解していると仮定する — 明示的なユーザー入力を必須にします

段階的な開示

コンテキストの使用量を最小限に抑えるよう、スキルを構成します。

1. メタデータ（約 100 トークン）：すべてのスキルについて、name と description が起動時に読み込まれます
2. 指示（5,000 トークン未満）：スキルが有効になると、完全な SKILL.md が読み込まれます
3. 参照（必要に応じて）：references/ 内のファイルは、必要な場合にのみ読み込まれます

SKILL.md は 500 行未満にしてください。詳細なドキュメントは参照ファイルに移してください。

参照ファイル

詳細なドキュメントには references/ を使用します。

references/
├── setup.md          # Installation and configuration
├── patterns.md       # Common patterns and examples
├── troubleshooting.md # Error solutions
└── api.md            # API reference

参照ファイルは次の条件を満たす必要があります。

• 1 つのトピックに絞られている
• 自己完結している（他のファイルがなくても読める）
• それぞれ 300 行未満である

SKILL.md から参照ファイルにリンクします。

## Reference Files

- [Setup](references/setup.md) - Installation and configuration
- [Patterns](references/patterns.md) - Common patterns and examples

スクリプト

エージェントが実行できる補助ツールには scripts/ を使用します。

scripts/
├── validate.sh       # Validation commands
├── setup.py          # Setup automation
└── check-version.sh  # Version checking

スクリプトは自己完結しており、エラー処理を含み、先頭に使用方法のコメントがある必要があります。allowed-tools で事前に許可してください（例：Bash(./scripts/validate.sh:*)）。

テンプレート

設定ファイル、ボイラープレート、またはスターターコードには templates/ を使用します。

templates/
├── config.yaml       # Default configuration
├── config-v2.yaml    # Version-specific variant
└── example-app/      # Starter project

テンプレートはエージェントがコピーまたは適用するものであり、直接実行するものではありません。

文章スタイル

すべてのスキルのコンテンツで Apollo Voice に従います。

トーン

• 親しみやすく、役に立つ
• 明確な見解を持ち、権威ある表現にする（推奨される進め方を示します）
• 率直で、行動を促す

言語

• アメリカ英語を使用する
• 簡潔な言葉を使い、慣用句は避ける
• 現在形と能動態を使う
• 指示には命令形の動詞を使う

書式

• 見出しにはセンテンスケースを使う
• 記号、コマンド、ファイルパス、URL にはコードフォントを使う
• ユーザーがクリックする UI 要素には太字を使う
• 順序なしリストにはハイフン（-）を使う

避ける表現

• 「Simply」、「just」、「easy」（見下したように聞こえる可能性があります）
• 「click here」のような曖昧な表現
• セミコロン（ピリオドを使います）
• Apollo を明確に指している場合を除き、「We」

参照ファイル

Apollo GraphQL 固有のガイダンスについては、次を参照してください。

• Apollo Skills - Apollo GraphQL スキルのパターンと例

バージョン管理

メタデータの version フィールドにはセマンティックバージョニング（"X.Y.Z"）を使用します。

metadata:
  author: apollographql
  version: "1.0.0"

• メジャー（X）：スキルの動作や有効化方法を変える後方互換性のない変更（例：トリガーの名前変更、セクションの削除、基本ルールの変更）
• マイナー（Y）：後方互換性を保ちながらコンテンツや機能を追加する変更（例：参照ファイルの追加、新しいセクション、例の拡充）
• パッチ（Z）：動作を変えない小規模な修正（例：誤字の修正、表現の調整、書式の修正）

新しいスキルは "1.0.0" から始めます。

新しいスキルのチェックリスト

スキルを公開する前に、次を確認します。

• name がディレクトリ名と一致し、命名規則に従っている
• description に、スキルの機能と使用する場面が明確に記載されている
• SKILL.md が 500 行未満である
• 参照ファイルがトピックごとに分かれており、それぞれ 300 行未満である
• 指示が明確で、実行可能である
• コード例が正しく、テスト済みである
• 基本ルールが ALWAYS/NEVER/PREFER 形式で記載されている
• コンテンツが Apollo Voice のガイドラインに従っている

基本ルール

• 必ず説明にトリガー条件を含めてください（番号付きリストを使用）
• 複数手順のプロセスでは、必ずチェックボックスを使用してください
• 詳細なドキュメントについては、必ずリファレンスファイルにリンクしてください
• SKILL.md は必ず500行以内にしてください
• エージェントがいつ有効化すべきか判断する助けにならない、曖昧な説明は絶対に使用しないでください
• 抽象的な説明より、具体例を優先してください
• 複数の選択肢を列挙するより、明確な方針を示すガイダンスを優先してください
• スキルに必要なツールを事前承認するには、allowed-tools を使用してください
• allowed-tools に Bash(curl:*) を絶対に含めないでください。これによりネットワークアクセスが無制限に許可され、curl | sh を使ったリモートコード実行につながるおそれがあります
• アクセス、キャッシュ、認証、シークレット、データの公開範囲を制御する設定やコードをスキルが生成する場合は、必ず ## Security セクションを含めてください
• セキュリティ上重要なガイダンスをリファレンスファイルのみに記載することは絶対に避けてください。LLM が必ず確認する SKILL.md に、重要な警告を記載してください
• セキュリティ上重要な設定を生成する前に、データモデルについてユーザーに質問するよう、必ず LLM に指示してください（例：ユーザー固有のフィールドと公開データの確認）
• セキュリティ上のリスクを生じさせる設定やコードのそばに、必ず明示的な引用形式の警告（> **Security: ...**）を記載してください
• セキュリティ上重要な機能ごとに、検証チェックリストの項目を追加し、必ず ## Security 見出しの下にまとめてください