skill-creator完全ガイド - Claude Skills開発フレームワーク実践解説¶

対象 / ポイント

対象: Claude Code、Claude.ai、Claude API向けのSkillを新規作成・改善したい開発者

ポイント:

skill-creatorは雛形生成だけでなく、テスト、比較、改善、トリガー最適化まで扱う
現在の基本ループは「作る→Skillあり／なしで評価→人が確認→直す」である
SKILL.mdは小さく保ち、決定論的処理をscripts/、詳細資料をreferences/へ分ける

「Skillを作って」と頼んでファイルが出た時点では、まだ完成ではない。現行のskill-creatorは、2〜3件の実タスクでSkillあり／なしを比較し、人の評価と定量指標を見ながら改善するところまでを一つの開発ループとして扱う。¹²

本記事の問いは、skill-creatorを使って、再利用できるだけでなく効果を説明できるSkillをどう作るかである。

skill-creatorの現在地¶

skill-creatorは、Agent Skillの作成・改善・評価を支援するSkillである。 新規作成だけでなく、既存Skillの修正、性能比較、トリガー精度の改善も対象に含まれる。²

基本の流れは次の通りだ。

flowchart LR
    A[意図を確認] --> B[SKILL.mdを作成]
    B --> C[2〜3件のテスト]
    C --> D[Skillあり／なしを比較]
    D --> E[人が成果物を確認]
    E --> F[指示・スクリプトを改善]
    F --> C
    E --> G[descriptionを最適化]
    G --> H[検証・パッケージ化]

従来の説明でよくあった「質問に答えればSKILL.mdを自動生成して終わり」という理解は不十分だ。現行版の中心は、Skillの有効性を比較しながら反復することにある。

Claude Codeへのインストール¶

Anthropic公式リポジトリをClaude Codeのプラグインマーケットプレイスとして登録し、skill-creatorを含むexample-skillsを導入する。¹

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

文書処理Skillも必要なら、別プラグインを追加する。

/plugin install document-skills@anthropic-agent-skills

skill-creatorはApache 2.0で公開されている。一方、docx、pdf、pptx、xlsxはsource-availableであり、同じライセンスではない。¹

インストール後は、自然文で明示的に呼び出せる。

skill-creatorを使って、Markdown記事を校正するSkillを作って

既存Skillの改善から始めることもできる。

skill-creatorを使って、このSkillの発動精度と出力品質を評価して改善して

最初に決める4項目¶

ファイルを書く前に、成功条件を固定する。 skill-creatorは会話履歴から既知の情報を拾い、不足分だけを確認する設計になっている。²

最初に決めるのは次の4項目だ。

SkillがClaudeに何をできるようにするか
どの依頼や文脈で発動すべきか
期待する出力形式は何か
テストケースを用意するか

ファイル変換、データ抽出、コード生成のように成否を判定できるSkillは、テストを付ける価値が高い。文章の雰囲気やアートのように主観評価が中心なら、無理に数値化せず、人のレビューを中心にしてよい。

Skillの標準構造¶

最小構成は、ディレクトリとSKILL.mdだけで成立する。 Agent Skillsの公開仕様では、次の構造が基本である。³

my-skill/
├── SKILL.md          # 必須: メタデータと指示
├── scripts/          # オプション: 実行可能コード
├── references/       # オプション: 参照資料
└── assets/           # オプション: テンプレートや素材

SKILL.mdのフロントマター¶

---
name: article-review
description: Markdown記事の事実、構造、表記を検査する。記事レビュー、校正、公開前確認を依頼されたときに使う。
compatibility: Requires Python 3.12 and network access for source verification
---

公開仕様上の主な制約は次の通りだ。³

フィールド	必須	主な制約
`name`	必須	最大64文字、小文字英数字とハイフン、親ディレクトリ名と一致
`description`	必須	最大1024文字、機能と使用場面の両方を書く
`license`	任意	ライセンス名または同梱ファイルへの参照
`compatibility`	任意	最大500文字、必要な製品・パッケージ・ネットワーク等
`metadata`	任意	追加メタデータのキー・値
`allowed-tools`	任意	実験的。実装間で対応差がある

Claude Platformの製品ドキュメントは、nameにanthropicとclaudeを含めない制約も示している。⁴ また、Agent Skills公開仕様はdescriptionを最大1024文字とする一方、Claude Help Centerは200文字上限と案内している。Claude製品間で持ち運ぶなら、200文字以内を実用上の安全側と考える。³⁵

descriptionが発動を決める¶

Claudeは常時、全Skillの本文を読むわけではない。起動時にはnameとdescriptionだけを読み、依頼と一致したSkillのSKILL.mdを後から読み込む。⁴

したがって、本文に「使用場面」を書くだけでは遅い。 descriptionには、次の2点を必ず含める。

Skillが何をするか
どの依頼、ファイル、文脈で使うか

「PDFを支援する」より、「PDFのテキスト抽出、フォーム入力、結合を行う。PDF、帳票、文書抽出の依頼で使う」の方が発動条件を判断しやすい。

Progressive Disclosureの設計¶

SKILL.mdにすべてを詰め込まず、必要な情報だけを段階的に読む。 公開仕様とAnthropicの実装は、3段階のロードを前提としている。²³

レベル	読み込む時点	内容
1. メタデータ	常時	`name`と`description`、約100トークン
2. 指示	発動時	`SKILL.md`本文、500行未満を推奨
3. リソース	必要時	scripts、references、assets

詳細なAPI仕様やドメイン別手順はreferences/へ移す。同じ計算や検査を毎回行うならscripts/へ移し、出力用テンプレートや画像はassets/に置く。

cloud-deploy/
├── SKILL.md
├── scripts/
│   └── validate_manifest.py
└── references/
    ├── aws.md
    ├── azure.md
    └── gcp.md

参照の連鎖を深くしすぎない。 SKILL.mdから必要なファイルへ直接案内し、大きな参照ファイルには目次を付ける。

現行の評価ループ¶

1. 現実的なテストを2〜3件作る¶

実際の利用者が入力する粒度のプロンプトを使う。 テストはevals/evals.jsonへ保存する。²

{
  "skill_name": "article-review",
  "evals": [
    {
      "id": 1,
      "prompt": "docs/blog/example.mdを公開前レビューして",
      "expected_output": "問題を優先度別に示したレビュー",
      "files": []
    }
  ]
}

「記事を見て」のような短すぎる入力だけでは、実運用の分岐を十分に試せない。ファイル名、目的、制約、曖昧さを含む入力を混ぜる。

2. Skillありとベースラインを同時に走らせる¶

新規Skillでは、同じタスクを次の2条件で比較する。

with_skill: 作成中のSkillを使う
without_skill: Skillを使わない

既存Skillを改善する場合は、旧版のスナップショットをベースラインにする。同じ時点で両条件を走らせることで、環境差を小さくする。

3. assertionと人の評価を分ける¶

機械で判定できる項目と、見て判断する品質を混同しない。 たとえば「CSVを生成した」「必須列が5つある」はassertionにできる。一方、「説明が読みやすい」「デザインが自然」は人が成果物を確認した方がよい。

現行版は、パス率だけでなく、実行時間とトークン数も記録する。品質が同じでも、Skillによって処理時間やコンテキスト消費が大きく増える場合があるためだ。

4. 評価ビューアーで成果物を見る¶

eval-viewer/generate_review.pyは、テストごとの成果物、形式評価、前回結果、フィードバック欄をまとめて表示する。² ヘッドレス環境では--staticを使い、単一HTMLへ出力できる。

python eval-viewer/generate_review.py \
  ../article-review-workspace/iteration-1 \
  --skill-name "article-review" \
  --benchmark ../article-review-workspace/iteration-1/benchmark.json \
  --static ../article-review-workspace/iteration-1/review.html

数値が改善しても、成果物が使いにくければ成功ではない。 skill-creatorが人のレビューをループに残している理由はここにある。

5. 改善して再実行する¶

失敗したテストだけに合わせた例外を増やすと、Skillは過学習する。複数テストで同じ処理が繰り返されているならスクリプト化し、指示が冗長なら削る。

改善後はiteration-2/へ結果を分け、前回版と比較する。人のフィードバックが空になった、利用者が満足した、または改善が頭打ちになったところで止める。

descriptionの発動精度を最適化する¶

出力品質と発動精度は別々に評価する。 良いSkillでも、必要なときに呼ばれなければ役に立たない。逆に、無関係な依頼で発動するとコンテキストと処理時間を浪費する。

現行のskill-creatorは、次の流れでdescriptionを改善する。²

発動すべき／すべきでない現実的なクエリを各8〜10件作る
近接領域の紛らわしい負例を含める
60%を学習、40%をホールドアウトへ分ける
各クエリを3回評価し、最大5反復で候補を改善する
学習側ではなくホールドアウト側の成績で採用案を選ぶ

実行例は次の通りだ。

cd /path/to/skill-creator
python -m scripts.run_loop \
  --eval-set /path/to/eval_set.json \
  --skill-path /path/to/article-review \
  --model <current-model-id> \
  --max-iterations 5 \
  --verbose

この処理はclaude -pを使うため、Claude.ai単体では実行できない。 Claude.aiでは、複数の発動プロンプトと非発動プロンプトを人が試し、descriptionを反復修正する。

検証とパッケージ化¶

skill-creatorには、構造検証と.skill作成用のスクリプトが同梱されている。¹²

cd /path/to/skill-creator

# フロントマターと命名を検証
python scripts/quick_validate.py /path/to/article-review

# .skill（ZIP形式）を作成
python -m scripts.package_skill /path/to/article-review ./dist

package_skillは検証に失敗すると停止し、ルート直下のevals/を配布物から除外する。公開仕様の検証だけが目的なら、skills-ref validate ./my-skillも利用できる。³

Claude Code・Claude.ai・APIの違い¶

同じSkill形式でも、配置と実行環境は異なる。

項目	Claude Code	Claude.ai	Claude API
導入	プラグイン、`.claude/skills/`、`~/.claude/skills/`	Customize > SkillsからZIP追加	Skills APIへアップロード
発動	`description`に基づく自動選択、明示指定も可能	有効化後に自動選択	containerで`skill_id`を指定
scripts	ローカル実行環境	Code Executionが必要	Code Executionコンテナ
ネットワーク	Claude Codeの権限設定に従う	実行環境に従う	Skill実行コンテナでは利用不可
依存追加	環境と権限に依存	標準リポジトリから導入可能	実行時インストール不可

APIでは、事前構築Skillならpptx、xlsx、docx、pdfのskill_idを使い、カスタムSkillは/v1/skillsでアップロードする。⁴ API上のSkillsはCode Executionと組み合わせるもので、単にsystem promptへ本文を貼る仕組みではない。

さらに、Agent Skills機能はZero Data Retentionの対象外である。データ保持要件があるシステムでは、導入前に現行ポリシーを確認する。⁴

セキュリティで外せない確認¶

第三者Skillは、文章ではなく実行可能な依存物として監査する。 Anthropicは、自作またはAnthropic提供のSkillを使い、不明なSkillは全ファイルを精査するよう案内している。⁴

確認対象は次の通りだ。

SKILL.mdが説明外の操作を指示していないか
scripts/が不要なファイルや認証情報へアクセスしないか
外部URLから取得した内容を命令として扱わないか
APIキーやパスワードがハードコードされていないか
パッケージやスクリプトの依存元を固定・監査できるか

Skillの説明が無害でも、同梱スクリプトや外部参照が安全とは限らない。「説明から予想できない動作をしない」というPrinciple of Lack of Surpriseを設計基準に置く。

使うべきケースと避けるケース¶

判断	向いているケース	別の手段がよいケース
再利用性	繰り返す多段タスク	一度だけの単純依頼
知識	組織固有の手順・基準	頻繁に変わる一時情報
実行	検証や変換をスクリプト化できる	外部サービス操作そのものが中心
評価	成果物や手順を比較できる	成功条件を定義できない

外部サービスへの接続が主目的ならMCPが適している。一方、MCPをどう使うかという組織手順はSkillにできる。両者は排他的ではない。

次の一手¶

skill-creatorの価値は、SKILL.mdを早く書くことだけではない。 Skillなしのベースラインより本当に良いかを確かめ、その証拠を残せることにある。

最初は小さなSkillと2〜3件のテストで始める。出力品質を確認し、繰り返される処理だけをスクリプト化し、最後に発動精度を最適化する。この順序なら、巨大な指示書を先に作ってしまう失敗を避けられる。