Claude Code Skillsの作り方と制作依頼への使い方

毎回貼っている確認手順をSkillにする

この記事では、架空の制作依頼8件（requests.json）と判定規則（judging-rules.md）を置いたフォルダで /production-review を呼び出し、8件それぞれの判定をJSONで受け取ります。判定規則は11条あり、記録するissue codeは10種類です。題材は制作依頼の確認をClaude Codeで進める記事で扱った作業です。前の記事では毎回プロンプトで指示していましたが、ここではその指示をSkillとして保存し、1行で呼び出せるようにします。

Claude Codeの公式ドキュメントは、同じ指示やチェックリスト、複数ステップの手順を何度もチャットに貼っているならSkillを作る場面だと説明しています。Skillの本文が読み込まれるのは使ったときだけです。メモリのドキュメントでも、CLAUDE.mdには毎回のセッションで必要な事実を書き、複数ステップの手順はSkillへ移すよう案内されています。この練習では、内容ごとに置き場所を次のように分けます。

CLAUDE.mdとSkillの使い分けはCLAUDE.mdの書き方ガイドでも説明しています。

練習フォルダにSkillを配置する

使う教材は2つです。練習セット（production-review-practice/）とSkill教材（skills-and-reviewers/）を、同じフォルダの中に展開してください。練習セットの中身は次の2つに分かれています。

• exercise/：入力の3ファイル（requests.json、judging-rules.md、prompt.txt）

• answer-key/：期待結果と照合スクリプト

期待結果をAIに見せないよう、作業フォルダには exercise/ の中身だけをコピーします。そこへSkill教材の .claude フォルダを追加してください。

# /path/to は各ZIPを展開した実際の場所へ置き換える
mkdir -p ~/cc-practice/request-check
cd /path/to/production-review-practice
cp -R exercise/. ~/cc-practice/request-check/
cd /path/to/skills-and-reviewers
cp -R .claude ~/cc-practice/request-check/

.claude は隠しフォルダです。Finderで見えなくてもコピーされています。prompt.txt は通常のプロンプト指示で使うファイルで、Skillで実行するこの記事では使いません。.claude/agents/ にある2つの担当定義も、ここでは使いません。コピー後のフォルダは次の形になります。

~/cc-practice/request-check/
├── requests.json
├── judging-rules.md
├── prompt.txt
└── .claude/
    ├── agents/
    │   ├── request-checker.md
    │   └── claim-checker.md
    └── skills/
        └── production-review/
            └── SKILL.md

.claude/skills/<skill-name>/SKILL.md は、プロジェクト単位のSkillを置く場所です。このフォルダで起動したセッションで読み込まれます。SKILL.md の全文は次のとおりです。

---
name: production-review
description: 架空の制作依頼について不足と矛盾を確認し確認先を返す
disable-model-invocation: true
allowed-tools: Read
---

# 制作依頼の確認

1. 作業フォルダの requests.json と judging-rules.md を読む
2. IDを一度ずつ残して全件を確認する
3. 空欄は補完せず矛盾とともに issue_codes に記録する
4. results 配列に id、decision、issue_codes、confirmation を含むJSONを返す
5. 外部送信と制作開始は行わない

frontmatterの役割と誤解しやすい点

--- で囲まれた部分には、呼び出し方と権限の扱いを書きます。

disable-model-invocation: true を付けておけば、確認を始めるタイミングを人が決められます。

allowed-tools はよく誤解される項目です。ドキュメントによると、この項目は列挙したツールをそのターンだけ事前承認するものです。次のメッセージを送ると承認は消えます。また、列挙していないツールも使える状態のまま残ります。ワークスペースの信頼確認とは関係なく適用されますが、組織が allowManagedPermissionRulesOnly を設定している環境では無視されます。つまり allowed-tools: Read と書いても、読むことしかできないSkillにはなりません。共有ドライブや社内サービスの認証、最小権限の設定を代わりに担うこともできません。

ツールを外したい場合は、範囲に合わせて使い分けます。

• Skillを使っている間だけ外す：disallowed-tools

• すべてのプロンプトで止める：権限設定のdenyルール

• 毎回必ず守らせたい規則がある：フック

本文5行目の「外部送信と制作開始は行わない」も、CLAUDE.mdと同じくClaudeへの指示です。強制力はありません。

/production-reviewを実行して8件を照合する

今回の実演で使ったコマンドは次のとおりです。printモード（-p）に /production-review の1行だけを渡しています。

cd ~/cc-practice/request-check
claude -p "/production-review" --tools Read,Skill --allowedTools Read,Skill --setting-sources project --strict-mcp-config --mcp-config '{"mcpServers":{}}'

--setting-sources project は、読み込む設定の範囲をprojectに絞る指定です。--strict-mcp-config と空の --mcp-config を組み合わせて、MCPサーバーを使わない条件にしています。実演の記録は次のとおりです。

今回の実演では、Claude CodeがWriteでファイルを書き出す操作は観測していません。手元で再現するときは、出力された results 配列のJSONを ~/cc-practice/request-check/actual-results.json として自分で保存してください。

対話モードで試すこともできます。その場合は作業フォルダで claude を起動し、メッセージの先頭に /production-review を入力します。返ってきたJSONは同じように保存してください。ただし、対話モードでの実行は今回計測していません。

返ってきたJSONから、results 配列の要素を2件抜粋します。R06は、尺の値が2か所で食い違っている依頼です。

{
  "results": [
    {
      "id": "R01",
      "decision": "ready",
      "issue_codes": [],
      "confirmation": "問題なし。すべての必須項目がそろっています。"
    },
    {
      "id": "R06",
      "decision": "hold",
      "issue_codes": [
        "conflicting_duration"
      ],
      "confirmation": "duration_seconds（15）と other_duration_seconds（30）が一致しません。どちらの尺が正しいか確認してください。"
    }
  ]
}

これは2件の抜粋です。照合用には実際に返った8件すべてを保存します。

答え合わせは練習セットの最上位フォルダに戻って行います。answer-key/ は作業フォルダにコピーしません。

cd /path/to/production-review-practice
python3 answer-key/check_result.py ~/cc-practice/request-check/actual-results.json

照合するのは id、decision、issue_codes の3項目です。confirmation の文章は照合の対象外です。今回は8件すべてが一致し、IDの重複もありませんでした。

この結果は、次の点に注意して読んでください。

• Skillの効果は示していない：同じ練習セットをプロンプトで直接指示した別の試行（計測教材の run-log.csv にあるbaselineの例）でも、8件すべてが一致しています。そのため、Skillで精度が上がったとも、時間が短くなったとも言えません。確かめられたのは、長い指示を貼り直さず1行で同じ確認を呼び出し、照合した3項目が期待結果と一致したことだけです。

• どの依頼でも同じになるとは限らない：結果は1回の実行に基づくものです。

• 読み込みの経路は断言できない：ツール呼び出しの記録はすべては保存していません。そのため、ClaudeがSKILL.mdや入力ファイルをどの経路で読んだかは断言できません。

実行の記録は計測教材の measurement-and-updates/observed/skill.json に収録しています。

うまく動かないときの戻し方

問題が起きたら、まずどの段階で止まっているかを切り分けます。表の手順は公式ドキュメントに基づくもので、今回の実演では試していません。

frontmatterの解析エラーは、claude --debug で起動するか、v2.1.233以降で使える次のコマンドで確認できます。

claude plugin validate .claude/skills

対話モードでSkillを直したら、Skillを書いていたときの会話を引き継がず、新しいセッションで試してください。ドキュメントの評価手順にあるとおり、作成時の会話が残っていると指示の書き漏れが見えにくくなります。

配布前に再実行して同じ条件を確かめる

今回の結果は1回分だけです。チームへ配る前に、次の手順で再実行してください。

1. 空の作業フォルダを用意し、exercise/ の3ファイルと .claude フォルダだけをコピーする

2. 上と同じ claude -p コマンドで /production-review を実行する

3. 出力を actual-results.json に保存し、練習セットの最上位フォルダで answer-key/check_result.py を使って照合する

4. Claude Codeのバージョン、モデル、一致件数、確認と修正にかかった時間を計測教材の run-log.csv に記録する

初回と再実行で照合結果がそろえば、少なくともその環境では、同じ条件で確認を呼び出せたと言えます。

チームで共有するときは、.claude/skills/ をリポジトリにコミットします。その前に、配布先の権限設定や組織の管理設定のもとで実際に動くかを試してください。allowed-tools の扱いは環境によって変わります。

制作依頼のSkill教材を受け取る