Agent Skills 実践ガイド — SKILL.md の書き方と Claude Code への組み込み | Singularity Society（シンギュラリティ・ソサエティ）

エディタで /code-review と打つだけで、組織標準のレビュー観点が走る。そんな運用をチームに広げたいとき、素のプロンプトでは続きません。Anthropic が 2025 年 10 月に公開した Agent Skills は、この「毎回書き直す指示」を packaged な資産に変える仕組みです。

一言で言えば、エージェントに「特定の仕事のやり方」をプロンプトとツールとサンプルひとまとめで渡す仕組みと言えます。Fine-tuning のようにモデルの重みは変えませんが、都度プロンプトを書き直すのとも違い、組織で蓄積・再利用できる専門性のパッケージになっています。

この記事では、なぜ Agent Skills が必要になったのか、SKILL.md の書き方と構造、スキル分割の原則(1 スキル = 1 ワークフロー)、MulmoTerminal / MulmoClaude での実運用例をまとめます。

なぜ Agent Skills が必要になったのか

問題: プロンプトの使い回しが辛い

Claude Code や Codex を日常的に使っていると、同じような指示を何度も書くことになります。コードレビューを 5 観点で、同じ worktree ルールで issue を立ち上げる、議事録のフォーマットを揃える、どれも繰り返しが多い作業です。

毎回全文を書き直すのは非効率ですし、過去のコピペ元を探し回るのも時間の浪費です。

既存の解決策とその限界

カスタムスラッシュコマンド

Claude Code の ~/.claude/commands/ に .md を置けばスラッシュコマンドを作れます。手軽ですが、プロンプトを 1 枚のファイルに書くだけなので、添付したいサンプルや参考資料を一緒にパッケージ化できません。Claude Desktop や Claude.ai との共有もしにくいです。

Fine-tuning

モデル自体を学習させる方法です。ただしデータ準備と計算リソースが高価ですし、失敗時のロールバックも面倒です。プラットフォームごとに対応状況も違い、「ちょっとした仕事を教える」用途には重すぎます。

Memory / RAG

長期記憶やベクトル検索で過去の文脈を引っ張ってくる方法です。ただし「このタイプの仕事をするには、こういう順序で、こういう形式で」という手続き的な知識は、retrieval より明示的に渡したほうがうまく動きます。ノイズを混ぜない設計も難しいです。

Agent Skills が埋める穴

モデルを変えずに、エージェントに「特定の仕事のやり方」をパッケージで渡す。これが Agent Skills の立ち位置です。Fine-tuning と単純なプロンプトの中間層を埋めます。

Agent Skills の構造

基本構造

my-skill/
├── SKILL.md          # エージェントが読む、このスキルの定義
├── reference-A.md    # 参考資料 (任意)
├── reference-B.md    # 参考資料 (任意)
└── templates/        # テンプレートファイル (任意)
    └── example.md

SKILL.md が中核で、残りはそこから参照する素材です。

SKILL.md の書き方

---
name: review-code
description: 現在のブランチの差分を 5 観点でレビューし、重要度順に 5 件まで問題を報告する
---

# review-code

このスキルは、現在のブランチの差分を以下の観点でレビューします。

## 観点

1. ロジックの正しさ
2. 既存コードとの整合性
3. テストカバレッジ
4. パフォーマンス懸念
5. セキュリティ懸念

## 手順

1. `git diff origin/main...HEAD` で差分を取得
2. 各観点でチェック
3. 発見した問題を重要度順に並べる
4. 修正案を可能な限り具体的に（コードスニペット付き）

## 出力形式

重要度 (High / Medium / Low) → ファイル:行 → 問題 → 修正案 の順で、1 件ずつ記述。

## 参照

- 既存のコーディング規約: [styleguide.md](styleguide.md)
- セキュリティチェックリスト: [security.md](security.md)

frontmatter の役割

name はスキル識別子で、短い kebab-case にします。description が最も重要で、LLM はこの説明を読んで「どのスキルを使うか」を決めます。「このスキルを呼び出すべき時」が明確に伝わる形で書きましょう。

body の役割

SKILL.md の本文は、スキルが呼び出されたときに LLM が読む内容です。「どういう手順で」「何を参照して」「どう出力するか」を具体的に書きます。

参照資料

同じディレクトリに .md や templates を置けば、SKILL.md から参照できます。大きな参考情報は本体ではなく参照資料に分割すると、context を節約できます。

スキル分割の原則

1 スキル = 1 ワークフロー

スキルは「汎用」ではなく「特定の仕事」に特化します。悪い例と良い例:

悪い例: 広すぎる

name: coding-helper
description: コーディングに関する手助けをする

これだと、LLM が「どういう時にこのスキルを呼ぶか」判断できない。

良い例: 具体的

name: review-pr-for-security
description: PR の差分をセキュリティ観点でレビューし、OWASP Top 10 に該当する問題を検出する

これなら、「セキュリティレビューしたい」と言われたときに即座に選ばれる。

スキルの粒度

目安は 100〜300 行の SKILL.md です。複数の手順を含む仕事は、スキル間で呼び出し合うよりも 1 スキルに step 1〜5 で書いたほうが明快になります。どうしても分割したい場合は、meta スキルから sub スキルを呼ぶ形にします。

他スキルとの境界

名前が似ているスキルは、description で明確な違いを宣言します。「このスキルは X を扱う、Y はスキル Z を使え」と書き分けておくと、LLM が迷いません。

Agent Skills を使えるプラットフォーム

Claude Desktop

~/.claude/skills/<name>/SKILL.md に置くと自動検出され、UI にも表示されます。

Claude Code

プロジェクト固有は .claude/skills/<name>/SKILL.md、全プロジェクト共通は ~/.claude/skills/<name>/ に置きます。

Claude.ai (web)

2025 年末から対応しており、チーム単位でスキルを共有できます。

MulmoTerminal / MulmoClaude

Claude Code の設定をそのまま継承するため、複数セルで同じスキルセットを並列に利用できます。

MulmoTerminal / MulmoClaude での実運用例

Singularity Society での運用

MulmoTerminal 開発チームでは、以下のようなスキルを運用しています。

refactor-safely — behavior preservation を verify する refactor ワークフロー
decompose-function — 長い関数の分割、テスト追加込み
code-review — 多軸レビュー、インラインコメント投稿
issue-draft — GitHub Issue の下書き作成
pr-babysit — PR の bot レビュー対応
simplify — 冗長なコードの整理
security-review — セキュリティ観点のレビュー

これらを .claude/skills/ 下に置き、ユーザが /<skill-name> でいつでも呼べる状態にしています。

スキル駆動のワークフロー

朝イチで /pr-babysit を叩いて前日の PR の bot コメントを捌き、設計時には /issue-draft で明確な issue を作ってから着手します。実装後は /code-review → /simplify → /security-review の 3 段。PR を出す前には /refactor-safely で behavior preservation を確認し、リリースは /release-app に任せます。

プロンプトを毎回書く時間を、スキルの磨き込みに回す、という流れに変わっていきます。

チーム内でスキルを共有する

repo の .claude/skills/ ディレクトリを commit に含めておけば、チーム全員が同じスキルを使えるようになります。新人の立ち上がりが早くなり(スキルを呼ぶだけで組織の標準が通る)、レビュー観点も揃い、属人化を防げます。組織的な AI 利用の標準化に効くポイントです。

スキルを書くときの落とし穴

description が広すぎると、LLM に選ばれません。「このスキルを使うべき時」を具体的に書くことが大事です。LLM は description を読んで判断するため、曖昧だと呼ばれなくなります。

body が長すぎて context を食う問題もよく起きます。SKILL.md 本文が 1000 行あると、スキルを呼ぶたびに大量のトークンが消費されます。本体は 100〜300 行に抑え、参照資料へ分割しましょう。

更新が追いつかない状況にも注意が必要です。コードベースや組織のルールが変わったのにスキルが古いままだと、エージェントが古いやり方で実装し続けます。スキル自体も PR で管理し、月 1 で見直す運用をおすすめします。

スキル間のコンフリクトも発生します。同じトリガーで複数スキルがマッチすると LLM が迷うので、description で明確に境界を切ります。

自分でスキルを書き始める最小ステップ

まず、毎週 3 回以上同じようなプロンプトを書いていることを 1 つ洗い出します。それがスキル化の候補です。

次に .claude/skills/<name>/SKILL.md を作ります。frontmatter に name と description、body に手順を書き、50 行で始めれば十分です。

1 週間ほど実際に呼び出して磨きます。「ここが足りない」「ここが余計」を調整し、呼ばれる description になるよう文言を調整します。

形が整ったら repo に commit し、チームに共有してフィードバックで更に磨きます。スキルが 3〜5 本溜まってきたら、それらを組み合わせたワークフローを設計する段階に入ります。

まとめ

Agent Skills を導入すると、「このタイプの仕事はこうやる」という組織の暗黙知が、呼び出せる形で手元に残っていきます。Fine-tuning より軽く、プロンプトの使い回しより組織的で、SKILL.md の description を磨けば LLM に選ばれるスキルになります。粒度は 1 スキル = 1 ワークフロー、100〜300 行が目安です。Claude Desktop / Code / Claude.ai のどこでも同じスキルが使え、MulmoTerminal や MulmoClaude で複数セルを並列実行するときには特に効きます。

プロンプトエンジニアリングから、コンテキストエンジニアリング、そしてスキルエンジニアリングへ。日々の作業を packaged な形で蓄積していく時代に入ってきました。

Agent Skills 実践ガイド — SKILL.md の書き方と Claude Code への組み込み