skill-creator

スキルクリエイター

専門知識やワークフローを追加して、エージェントの能力を拡張する opencode スキルを作成します。

スキルでできること

• 専門的なワークフロー - 特定の分野における複数ステップの手順
• ツールとの連携 - ファイル形式、API、ライブラリに関する指示
• ドメインの専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
• 同梱リソース - 再利用可能なスクリプト、リファレンス、アセット

スキルの配置場所

範囲	パス
プロジェクト	.opencode/skill/<name>/SKILL.md
グローバル	~/.config/opencode/skill/<name>/SKILL.md

• プロジェクトスキル：チームで共有する、リポジトリ固有のスキル（例：our-api-patterns、project-deploy）
• グローバルスキル：すべてのプロジェクトで使う個人用ツール（例：pdf-editor、commit-helper）

プロジェクトのパスの場合、OpenCode は cwd から git worktree のルートまでさかのぼって検索します。

スキルの構造

skill-name/
├── SKILL.md              # Required - frontmatter + instructions
├── scripts/              # Optional - executable code (Python/Bash)
├── references/           # Optional - docs loaded on-demand
└── assets/               # Optional - templates, images, fonts

SKILL.md の形式

---
name: skill-name
description: [Self-contained workflow summary — see guidelines below]
---
# Instructions here (markdown body)

Name：短いハイフン区切りの識別子です。わかりやすく簡潔にしてください（最大64文字）。

Description：エージェントはスキルを読み込む前に、これと名前を確認します。次の内容を含め、単独で意味が通じるようにしてください。

• 提供するワークフローや機能
• 適用すべき状況を示す「Use proactively when」のトリガー
• 具体例を3〜5件

重要：description フィールドは、主なトリガーの仕組みです。

スキルはSOP／ワークフローであり、エージェントではありません。「あなたは〜です」や「［役割］の専門家です」のような役割の説明は使用しないでください。

読み込み前に、エージェントが <available_skills> で確認できるのは名前と説明だけです。

<available_skills>
  <skill>
    <name>skill-name</name>
    <description>...</description>
  </skill>
</available_skills>

説明だけで内容がわかるようにしてください。エージェントは「何をするものか」を確認するためだけにスキルを読み込むことはありません。

名前と説明は組み合わせて機能させてください。

• 名前：短いハイフン区切りの識別子（例：typescript-advanced）
• 説明：機能、トリガー、例を含む、単独で意味が通じるワークフローの概要

説明のパターン（LLM 向けに最適化）：

---
name: skill-name
description: |-
  [Action verb/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---

情報密度が高く、機械で解析できる具体的な記述にしてください。散文は避けてください。

重要：YAML の構文： 例を含む複数行の説明には、必ずリテラルブロックスカラー（|-）を使ってください。ハイフンは末尾の改行を取り除きます。引用符で囲まないコロンやリストを含む通常の YAML は使用しないでください。

# ❌ WRONG - breaks YAML parsing
description: Handle plugins. Examples:
- user: "..." → action

# ✅ CORRECT - use |- for multi-line
description: |-
  Handle plugins.
  
  Examples:
  - user: "..." → action

例：

---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  erasable syntax compliance, and test writing. Use proactively for complex generics,
  conditional types, utility types, TS compiler config, or test authoring.
  
  Examples:
  - user: "Create a type-safe event emitter" → implement with generics and mapped types
  - user: "Migrate to strict TypeScript" → add discriminated unions, exhaustive checks
  - user: "Build typed API client from OpenAPI" → generate request/response types with inference
  - user: "Write unit tests" → create strict, typed tests with realistic fixtures
---

要件：

• 動作を表す動詞から始めてください（「あなたは〜です」や「［役割］の専門家です」は不可）
• 具体的な機能を列挙してください（「X を支援」のような曖昧な表現は無視されます）
• 適用すべき状況を示す「Use proactively when」のトリガーを含めてください
• user: "..." → ... の形式で具体例を3〜5件提示してください
• 複数行の説明には |- リテラルブロックスカラーを使ってください（リストやコロンを含む通常の YAML は解析エラーになります）
• 情報密度を高め、LLM が解析できるようにしてください。説明だけで読み込む価値が伝わる必要があります

重複を減らす： SKILL.md の本文で説明の内容を繰り返さないでください。

同梱リソース

ディレクトリ	用途	使用するタイミング
scripts/	再利用可能な Python／Bash コード	同じコードを何度も書き直すとき
references/	ドキュメント、スキーマ、API 仕様	作業中にエージェントが情報を必要とするとき
assets/	テンプレート、画像、フォント	出力で使うファイル（読み込み対象ではありません）

含めてはいけないもの：README.md、CHANGELOG.md、INSTALLATION_GUIDE.md、その他の補助ドキュメント。スキルには、エージェントが作業を行うために必要なものだけを含めてください。

基本原則

簡潔にする

コンテキストウィンドウは共有されています。エージェントがすでに知っている情報は追加しないでください。

• 各段落について、「トークンを使うだけの価値があるか」を検討してください
• 説明より例を優先してください
• SKILL.md は500行未満にすることを推奨します

壊れやすさに応じて自由度を調整する

自由度	形式	使用する場面
高	テキストによる指示	有効な方法が複数ある場合
中	擬似コード／パラメーター化されたスクリプト	推奨パターンがある場合
低	専用スクリプト	壊れやすい操作や、一貫性が重要な場合

段階的な開示

1. メタデータ（名前＋説明） - 常に読み込まれます（約100語）

   • description は主要な発見手段です
   • エージェントはこれを見て、スキルを読み込むかどうかを判断します
   • 説明が曖昧だと、スキルは使われません

2. SKILL.md の本文 - スキルが起動したときに読み込まれます

   • 中核となるワークフローと詳細な指示
   • エージェントが作業を行うために必要な内容に絞ります

3. 同梱リソース - エージェントが必要に応じて読み込みます

   • バリエーション固有の詳細は references/ に移します

中核となるワークフローは SKILL.md に記載します。バリエーション固有の詳細は references/ に移します。

構成例：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

エージェントは関連するプロバイダーファイルのみを読み込みます。

作成プロセス

1. 理解 → 具体的な使用例を集めます
2. 計画 → 再利用可能なスクリプト／リファレンス／アセットを特定します
3. 初期化 → ディレクトリと SKILL.md を手動で作成します
4. 編集 → SKILL.md のフロントマターと本文を記述し、リソースを追加します
5. 検証 → スキルが正しく読み込まれ、起動することを確認します
6. 反復 → テストして改善し、繰り返します

ステップ 1：理解

スキルの使用方法について、具体的な例を集めます。次の質問をします：

• 「このスキルには何をさせますか？」
• 「どのようなリクエストで起動すべきですか？」
• 「ユーザーからの問い合わせ例を挙げてもらえますか？」

使用パターンがすでに明確な場合に限り、このステップを省略します。

ステップ 2：計画

各ユースケースについて、再利用可能なリソースを特定します：

何度も行うこと...	追加先...
同じコードを書き直す	scripts/
スキーマ／ドキュメントを再確認する	references/
同じテンプレートをコピーする	assets/

例：

• pdf-editor：「この PDF を回転して」→ scripts/rotate_pdf.py
• bigquery：「今日のユーザー数は？」→ references/schema.md
• frontend-builder：「ToDo アプリを作って」→ assets/react-template/

ステップ 3：初期化

スキルディレクトリと SKILL.md を手動で作成します：

# Global skill (personal tools)
mkdir -p ~/.config/opencode/skill/my-skill

# Project skill (team-specific)
mkdir -p .opencode/skill/my-skill

フロントマターを含む SKILL.md を作成します：

---
name: my-skill
description: |-
  [Workflow/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---
# [Skill Name]

[Instructions start here]

説明のテンプレート例：

---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  and test writing. Use proactively for complex generics, conditional types, utility types, TS compiler
config, or test authoring.

Examples:
- user: "Create a type-safe event emitter" → implement with generics and mapped types
- user: "Migrate to strict TypeScript" → add discriminated unions, exhaustive checks
- user: "Build typed API client from OpenAPI" → generate request/response types with inference
- user: "Write unit tests" → create strict, typed tests with realistic fixtures
---

必要に応じて、オプションのディレクトリを追加します：

cd my-skill
mkdir scripts references assets  # only create what you'll actually use

ステップ 4：編集

記述ガイドライン：

• 命令形を必ず使用します（「スクリプトを実行する」。「実行してください」ではありません）
• 文章より箇条書きを推奨します
• 詳細情報についてはリファレンスへのリンクを推奨します
• 含める前に、すべてのスクリプトを必ずテストします

フロントマターの要件：

• name：小文字とハイフンを使う形式とし、ディレクトリ名と完全に一致させます
• description：重要です — 上記の で指定した形式に従います。エージェントはこれを使ってスキルを見つけます。

ステップ 5：検証

スキルを見つけられることを確認します：

1. 構成を確認する：

   • スキルディレクトリに SKILL.md が存在する
   • ディレクトリ名がフロントマターの name: と完全に一致する
   • YAML フロントマターが有効である

2. 発見をテストする：

   • スキルがエージェントの <available_skills> セクションに表示される
   • 説明が、関連する問い合わせに一致するだけの具体性を備えている

3. 起動条件を確認する：

   • 説明を読んだだけで、このスキルをいつ使うべきか判断できますか？
   • 例は主なユースケースを網羅していますか？

注： スキルはディレクトリから直接使用します。パッケージ化やインストールの手順は不要です。

ステップ 6：反復

実際に使用した後：

1. スキルが起動しなかったり、指針が不明確だったりする箇所を確認します
2. 起動対象として不足している状況を含めるよう、description を更新します
3. description または SKILL.md の本文に例を追加します
4. 発見と起動条件を再検証します

エージェントの権限

エージェント設定で、エージェントごとのスキルアクセスを制御します：

{
  "permission": {
    "skill": { "*": "deny", "my-skill": "allow" }
  }
}

値："allow"、"deny"、"ask"。デフォルトのワイルドカードとして "*" を使用します。

<question_tool>

まとめて質問する： 関連する質問が2つ以上ある場合は question ツールを使用します。質問が1つだけの場合は、通常のテキストで尋ねます。

構文： header は12文字以内、label は1〜5語にします。デフォルトには「(Recommended)」を付けます。

質問するタイミング：リクエストが曖昧な場合、複数のスキルパターンが当てはまる場合、または範囲が不明確な場合。

</question_tool>

<bundled_references>

利用可能なリファレンス

このスキルには、高度なパターンに関するリファレンスドキュメントが含まれています。必要に応じて読み込んでください。

リファレンス	読み込むタイミング
references/output-patterns.md	テンプレート出力の設計、例に基づくガイダンス
references/workflows.md	順次または条件付きのワークフロー構造

使い方： コアワークフローを超える詳細なパターンが必要な場合は、該当するリファレンスファイルを読み込んでください。

</bundled_references>