スキルの書き方
スキルはClaude Codeの再利用可能なプロンプトです。SKILL.mdファイルとして定義し、バージョン管理されます。
SKILL.md の構造
Section titled “SKILL.md の構造”---name: my-skilldisplay_name: My Skilldescription: スキルの説明(一行)---
ここにプロンプトの本文を記述します。フロントマター
Section titled “フロントマター”| フィールド | 必須 | 説明 |
|---|---|---|
name | Yes | スラッグ識別子(/^[a-z0-9-]+$/) |
display_name | Yes | 人間向けの表示名 |
description | Yes | スキルの説明(一行) |
requires | No | 依存宣言(下記参照) |
依存宣言(requires)
Section titled “依存宣言(requires)”スキルが必要とする外部依存を requires ブロックで宣言できます。ワークフロー実行前にミニオンが必要なツールや設定を持っているか事前チェックされます。
---name: lancers-compe-searchdescription: ランサーズコンペ検索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 ブロックがないスキルは「外部依存なし」として扱われます。
プロンプト本文
Section titled “プロンプト本文”Markdown形式で記述します。Claude Codeがこのテキストを指示として受け取り、実行します。
変数とシークレット
Section titled “変数とシークレット”スキルでは、設定パラメータにテンプレート変数、機密情報にシークレットの2つの仕組みで外部値を参照できます。
テンプレート変数({{VAR_NAME}})
Section titled “テンプレート変数({{VAR_NAME}})”スキル本文中に {{VAR_NAME}} と記述すると、実行時に変数の値で自動的に置換されます。
---name: deploy-sitedescription: 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)
Section titled “シークレット($SECRET_NAME)”シークレットは環境変数として実行プロセスに注入されます。APIキーやパスワードなどの機密情報に使用します。
---name: check-apidescription: 外部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で必要なシークレットを宣言すると、実行前バリデーションが行われる
シークレットのスコープ
Section titled “シークレットのスコープ”ミニオンは 1 つのワークスペースに所属し、シークレットはそのワークスペースの分としてミニオンの上に保存されます。実行には、そのスキルが requires.env_vars で宣言したものだけが渡ります。ミニオンがほかのワークスペースの分を持っていれば、次につながったときにミニオンが消します (シークレットも)。
以前の版 (Node.js 版) のミニオンには「ミニオン全体」のスコープ (workspace_id='') もあり、そのミニオンのどのセッションからも見えます。同じキーがワークスペース側にあれば、ワークスペース側が勝ちます。
スキルの管理
Section titled “スキルの管理”ミニオンの上では
Section titled “ミニオンの上では”ミニオンがスキルを実行するとき、Minion Workspace がそのスキルの今の版を渡し、ミニオンの ~/.claude/skills/<name>/SKILL.md に置きます。この写しを直しても何も変わりません。次の実行でまた Minion Workspace から渡されます。
ミニオンが加える変更
Section titled “ミニオンが加える変更”ミニオンは hq push skill <name> で、スキルの変更(や新しいスキル)を提案できます。Minion(今の版)では 下書き として届き、ワークスペースの誰かが スキル → ミニオンからの下書き で中身を確かめて公開するまで、スキルは変わらず、どの実行も下書きを使いません。
以前の版(Node.js 版)のミニオンは minion-cli skill list|fetch|push を使い、push するとそのまま新しい版ができます。
付随ファイル
Section titled “付随ファイル”スキルはSKILL.mdに加え、テンプレートや設定ファイルを含めることができます。同じディレクトリ内のファイルがすべてスキルの一部として管理されます。
~/.claude/skills/my-skill/├── SKILL.md # プロンプト本文├── template.html # テンプレートファイル└── config.json # 設定ファイル外に公開する
Section titled “外に公開する”作ったスキルは、ワークスペースの外の人にも読めるように公開できます。公開したスキルは、見た人が自分のワークスペースに複製できます。手順は公開共有を、外から何が見えるかは公開されるものを参照してください。