スキルの書き方

スキルはClaude Codeの再利用可能なプロンプトです。SKILL.mdファイルとして定義し、バージョン管理されます。

SKILL.md の構造

---
name: my-skill
display_name: My Skill
description: スキルの説明（一行）
---

ここにプロンプトの本文を記述します。

フロントマター

フィールド	必須	説明
`name`	Yes	スラッグ識別子（`/^[a-z0-9-]+$/`）
`display_name`	Yes	人間向けの表示名
`description`	Yes	スキルの説明（一行）
`requires`	No	依存宣言（下記参照）

依存宣言（requires）

スキルが必要とする外部依存を requires ブロックで宣言できます。ワークフロー実行前にミニオンが必要なツールや設定を持っているか事前チェックされます。

---
name: lancers-compe-search
description: ランサーズコンペ検索
requires:
  mcp_servers: [playwright, supabase]
  cli_tools: [git, node]
  env_vars: [LANCERS_EMAIL, LANCERS_PASSWORD]
---

フィールド	説明
`mcp_servers`	必要なMCPサーバー（`~/.mcp.json` の設定と照合）
`cli_tools`	必要なCLIツール（任意のツール名を指定可能。ミニオン上で `which` により動的チェック）
`env_vars`	必要な環境変数（ミニオンローカルの変数/シークレット、およびHQ注入のプロジェクト/ワークフロー変数と照合）

requires ブロックがないスキルは「外部依存なし」として扱われます。

プロンプト本文

Markdown形式で記述します。Claude Codeがこのテキストを指示として受け取り、実行します。

変数とシークレット

スキルでは、設定パラメータにテンプレート変数、機密情報にシークレットの2つの仕組みで外部値を参照できます。

テンプレート変数（`{{VAR_NAME}}`）

スキル本文中に {{VAR_NAME}} と記述すると、実行時に変数の値で自動的に置換されます。

---
name: deploy-site
description: Webサイトをデプロイする
---

{{SITE_URL}} を {{DEPLOY_TARGET}} にデプロイしてください。

変数は4つのスコープで定義でき、同名キーは優先度の高いスコープが上書きします:

優先度	スコープ	設定場所	説明
1（最低）	ワークスペース	HQダッシュボード → ワークスペース設定	配下の全ミニオン・プロジェクトで共有
2	プロジェクト	HQダッシュボード → プロジェクト設定	プロジェクトメンバー間で共有
3	ワークフロー	HQダッシュボード → ワークフロー設定	ワークフロー固有の上書き
4（最高）	ミニオン	HQダッシュボード → ミニオン設定、または `PUT /api/variables/:key`	実行マシン固有の最終オーバーライド（12-factor app流）

変数名: 英数字とアンダースコアのみ（\w+）
未定義の変数は {{VAR_NAME}} のまま残る（エラーにはならない）
テンプレート展開はデプロイ時ではなく実行時に行われる
ワークスペース／プロジェクト／ワークフローはHQ側で展開され、ミニオン側のローカル変数が最後に上書きする。ミニオン運用者がHQ側を変更せずに値を差し替えられる経路を保証する

シークレット（`$SECRET_NAME`）

シークレットは環境変数として実行プロセスに注入されます。APIキーやパスワードなどの機密情報に使用します。

---
name: check-api
description: 外部APIのヘルスチェック
requires:
  env_vars: [API_KEY]
---

$API_KEY 環境変数のAPIキーを使用してエンドポイントを呼び出してください。

シークレットはHQダッシュボード（ミニオン設定）または PUT /api/secrets/:key で設定します。変数との違い:

シークレットの値は一覧APIで返却されない（キーのみ）。HQ DBには一切保存されない。HQはpass-throughとして値を中継するのみ。
{{VAR}} テンプレートとして展開されない — プロセスの環境変数 $ENV_VAR として利用可能
フロントマターの requires.env_vars で必要なシークレットを宣言すると、実行前バリデーションが行われる

シークレットのスコープ（マルチワークスペース対応）

1つのミニオンが複数のワークスペースを担当する場合、漏洩防止のためミニオン側でスコープ別に保存されます:

スコープ	保存形式	セッションから参照可能な条件
ミニオン全体	`workspace_id=''`	常に（どのワークスペースでも、ad-hocコマンドでも）
ワークスペース別	`workspace_id=<uuid>`	ランナーがそのワークスペースのコンテキストで実行している時のみ

同じキーが両方のスコープに存在する場合はワークスペース側が勝ちます。スキル側はどちらのスコープに由来するかを意識する必要はなく、$KEY で参照すれば適切な値が渡されます。

ダッシュボードでシークレットを登録する際にスコープを選んでください:

ミニオン全体: このミニオンが担当する全ワークスペースで共有したい認証情報（例: 自分の OPENAI_API_KEY を開発用に共有）
ワークスペース別: 顧客・テナント固有の認証情報。ワークスペースごとに個別登録することで、ワークスペースAのキーがワークスペースBの実行中に見えることはありません

スキルの管理

ローカルでの配置

スキルはミニオンの ~/.claude/skills/<name>/SKILL.md に配置されます。

# ローカルのスキル一覧を確認
minion-cli skill list --local

HQとの同期

# HQ上のスキル一覧
minion-cli skill list

# スキルをHQから取得してローカルにデプロイ
minion-cli skill fetch <name>

# ローカルのスキルをHQにpush（新バージョンが自動作成）
minion-cli skill push <name>

付随ファイル

スキルはSKILL.mdに加え、テンプレートや設定ファイルを含めることができます。同じディレクトリ内のファイルがすべてスキルの一部として管理されます。

~/.claude/skills/my-skill/
├── SKILL.md           # プロンプト本文
├── template.html      # テンプレートファイル
└── config.json        # 設定ファイル