> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# skill-creator - スキル作成

> スキルの作成・インストール・更新、SKILL.md の書き方とディレクトリ構成の標準化

`skill-creator` は「メタスキル」です。Agent が他のスキルを作成・インストール・更新する際に呼び出され、すべてのスキルの `SKILL.md` の書き方とディレクトリ構成を統一します。

## いつ起動するか

* ユーザーが URL やリモートリポジトリからスキルをインストールしたいとき
* ユーザーが新しいスキルをゼロから作成したいとき
* 既存のスキルをアップグレード・リファクタリングする必要があるとき

## スキルとは

スキルは「再利用可能な説明書」にオプションのスクリプトやリソースを加えたものです。特定のドメインの専門知識を Agent に注入し、該当タスクをスペシャリストのように処理できるようにします。

スキルには通常、以下が含まれます：

1. **専門ワークフロー** — ある種のタスクの完全な手順
2. **ツールの使い方** — 特定の API やファイル形式の処理方法
3. **ドメイン知識** — チームの規約、ビジネスルール、データ構造など
4. **付属リソース** — スクリプト、参考ドキュメント、テンプレートなど

<Note>
  **基本原則：省けるものは省く。** Agent が自力で推測できない内容だけを書きましょう。1 行追加するたびに「このトークンコストに見合うか？」と自問してください。
</Note>

## ディレクトリ構成

```
skill-name/
├── SKILL.md            # 必須：スキル定義
│   ├── YAML frontmatter（name / description は必須）
│   └── Markdown 本文（説明 + 例）
└── オプションリソース
    ├── scripts/        # 実行可能スクリプト（Python / Bash など）
    ├── references/     # 分量が多い参考ドキュメント（Agent が必要時に読む）
    └── assets/         # テンプレート、アイコンなど（出力に直接使われるもの）
```

## SKILL.md 仕様

SKILL.md ヘッダーの `frontmatter` フィールド：

| フィールド                                | 説明                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `name`                               | スキル名。小文字＋ハイフン、ディレクトリ名と一致させる                                                                       |
| `description`                        | **最も重要なフィールド**。「このスキルが何をするか」「いつ使うべきか」を明記する。Agent はこれを見て呼び出すかどうかを判断する。トリガーに関する記述はすべてここに書き、本文には書かない |
| `metadata.cowagent.requires.bins`    | システムに必要な CLI ツール                                                                                  |
| `metadata.cowagent.requires.env`     | 必要な環境変数（すべて揃っている必要がある）                                                                            |
| `metadata.cowagent.requires.anyEnv`  | 複数の API Key のうち 1 つあればよい                                                                          |
| `metadata.cowagent.requires.anyBins` | 複数のツールのうち 1 つあればよい                                                                                |
| `metadata.cowagent.always`           | `true` にすると常にロードされ、依存チェックをスキップ                                                                    |
| `metadata.cowagent.emoji`            | 表示用の絵文字（任意）                                                                                       |
| `metadata.cowagent.os`               | OS 制限、例: `["darwin", "linux"]`                                                                    |

<Note>
  `category` フィールドは手動で設定する必要はありません。システムが自動的に `skill` に設定します。
</Note>

API Key 依存の宣言方法は 2 通り：

```yaml theme={null}
metadata:
  cowagent:
    requires:
      env: ["MYAPI_KEY"]            # 必須
```

```yaml theme={null}
metadata:
  cowagent:
    requires:
      anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]   # いずれか 1 つ
```

**スキルは依存関係に基づいて自動的に有効/無効になります**：環境変数が揃えば自動有効、不足すれば自動無効。手動で `/skill enable` する必要はありません。

## リソースディレクトリの使い方

| ディレクトリ        | 入れるもの                                               | 入れないもの                  |
| ------------- | --------------------------------------------------- | ----------------------- |
| `scripts/`    | 繰り返し実行するコード、確定的な結果が必要なスクリプト                         | デモ用のコード片                |
| `references/` | **500 行超**で SKILL.md に収まらない大きなドキュメント（完全な DB スキーマなど） | 一般的な API ドキュメント、チュートリアル |
| `assets/`     | 最終出力に含まれるファイル（テンプレート、アイコン、ボイラープレートなど）               | 説明用ドキュメント               |

<Warning>
  **原則としてすべての内容を `SKILL.md` に書きます** — リソースディレクトリに分割するのは本当に収まらない場合だけです。

  `README.md`、`CHANGELOG.md`、`INSTALLATION_GUIDE.md` などをスキルに追加しないでください。すべて `SKILL.md` に入れましょう。リソースディレクトリには実際に実行するスクリプトや実際に使う素材だけを配置してください。
</Warning>

## 外部スキルのインストール

インストール後、スキルは `<workspace>/skills/<name>/` に配置されます。

| ソース            | インストール方法          |
| -------------- | ----------------- |
| URL（単一ファイル）    | curl / web\_fetch |
| URL（zip アーカイブ） | ダウンロードして展開        |
| ローカル SKILL.md  | 直接読み込み            |
| ローカル zip アーカイブ | 展開                |

インストール手順：

1. `SKILL.md` を見つける（アーカイブのルートまたはサブディレクトリにある場合がある）
2. frontmatter から `name` を読み取る
3. **スキルディレクトリ全体**（`SKILL.md`、`scripts/`、`assets/` など）を `<workspace>/skills/<name>/` にコピー
4. アーカイブに `INSTALL.md` などのセットアップスクリプトがあれば実行するが、最終的に `<workspace>/skills/<name>/` に収まっている必要がある

## スキルをゼロから作成

推奨手順：

1. **要件を明確にする** — ユーザーに具体的なユースケースをいくつか挙げてもらう（一度に多く聞きすぎない）

2. **構成を計画する** — スクリプトは必要か？参考ドキュメントは？テンプレートは？

3. **スキャフォールド** — 初期化スクリプトを使用：

   ```bash theme={null}
   scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
   ```

4. **内容を埋める** — SKILL.md を書き、スクリプトとリソースを追加。スクリプトは必ず実行テストする

5. **バリデーション**（任意）：

   ```bash theme={null}
   scripts/quick_validate.py <workspace>/skills/<skill-name>
   ```

6. **イテレーション** — 実際の使用フィードバックに基づいて継続的に改善

## 命名規則

* 小文字、数字、ハイフンのみ使用。ユーザーの入力は正規化する（例: `Plan Mode` → `plan-mode`）
* 64 文字以内
* 短く、動詞で始め、一目で何をするか分かるように
* 必要に応じてツール名をプレフィックスにする（例: `gh-address-comments`、`linear-address-issue`）
* ディレクトリ名と `name` フィールドは完全に一致させる

## 3 段階ローディング

スキルは一度にすべてコンテキストに読み込まれるわけではなく、3 段階で必要に応じてロードされます：

1. **メタ情報**（`name` + `description`） — 常にコンテキスト内（約 100 語）。Agent がスキルを使うかどうかの判断に使用
2. **SKILL.md 本文** — スキルが有効化されたときだけロード。500 行以内を推奨
3. **リソースファイル** — Agent が必要なときに読み込む

複数のバリエーション（例: マルチクラウドデプロイ）を持つスキルは次のように整理：

```
cloud-deploy/
├── SKILL.md             # メインワークフローとプロバイダー選択ロジック
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

ユーザーが AWS を選んだら、Agent は `aws.md` だけを読みます。3 社分のドキュメントをすべてロードする必要はありません。

## よくあるデザインパターン

**ステップ式**：番号付きの手順と対応スクリプト。

```markdown theme={null}
1. フォーム構造を分析（analyze_form.py を実行）
2. フィールドマッピングを生成（fields.json を編集）
3. フォームを自動入力（fill_form.py を実行）
```

**分岐式**：ユーザーの意図に応じて異なるフローへ。

```markdown theme={null}
1. 操作タイプを判定：
   **新規作成？** → 「作成フロー」へ
   **既存の編集？** → 「編集フロー」へ
```

**テンプレート式**：出力形式に厳密な要件がある場合、SKILL.md にテンプレートを含め、Agent にそれに従って出力させる。