Agent Skills とは — 自作スキルで Claude に専門性を注入する実践ガイド | Singularity Society（シンギュラリティ・ソサエティ）

Anthropic が 2025 年 10 月に導入した Agent Skills は、2026 年の AI エージェント運用で急速に広がっている仕組みです。

一言で言うと:

エージェントに「特定の仕事のやり方」を、プロンプト + ツール + サンプルの packaged な形で渡す仕組み

Fine-tuning のようにモデルの重みを変えません。でも、プロンプトを都度書き直すのとも違います。組織的に蓄積・再利用できる専門性のパッケージです。

本稿では、

なぜ Agent Skills が必要になったのか
SKILL.md の書き方・構造
スキル分割の原則（1 スキル = 1 ワークフロー）
MulmoTerminal / MulmoClaude での実運用例

を整理します。

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

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

Claude Code や Codex を日常的に使っていると、同じような指示を何度も書くことになります。

「このコードを review して、こういう観点で問題を 5 件まで挙げて…」
「この issue を worktree で開始して、ブランチ名はこの形式で…」
「この議論を議事録として、こういうフォーマットで…」

毎回全文書くのは非効率。コピペ元のメモを探すのも非効率。

既存の解決策とその限界

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

Claude Code の ~/.claude/commands/ に .md を置くと、スラッシュコマンドが作れる。これは良い。でも:

プロンプトを 1 枚のファイルに書くだけ
添付したいサンプルファイルや参考リソースを一緒に paquete 化できない
プラットフォーム（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 の role

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

body の役割

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

参照資料

同じディレクトリに .md や templates を置くと、SKILL.md から参照できる
大きな参考情報は、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 を使え」と書く

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 に含めれば、チーム全員が同じスキルを使えます。

新人エンジニアの立ち上がりが早くなる (スキルを呼ぶだけで組織の標準が通る)
レビュー観点が揃う (/code-review が同じ観点を見る)
属人化を防ぐ

組織的な AI 利用の標準化 に効きます。

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

1. description が広すぎて選ばれない

「このスキルを使うべき時」を具体的に書くこと。LLM は description を読んで判断するので、ここが曖昧だと使ってもらえない。

2. body が長すぎて context を食う

SKILL.md 本文が 1000 行あると、スキルを呼ぶたびに大量のトークンが消費される。本体は 100-300 行、参照資料に分割。

3. 更新が追いつかない

コードベースや組織のルールが変わったのに、スキルが古いまま → エージェントが古いやり方で実装し続ける。

スキルも PR で管理し、月 1 で見直す 運用を推奨。

4. スキル間のコンフリクト

同じトリガーで複数スキルがマッチすると、LLM が迷う。description で明確に境界を切る。

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

Step 1: 繰り返しやっていることを 1 つ洗い出す

毎週 3 回以上同じようなプロンプトを書いているなら、スキル化の候補。

Step 2: `.claude/skills/<name>/SKILL.md` を作る

frontmatter に name と description、body に手順を書く。50 行で始める。

Step 3: 1 週間使って磨く

実際に呼び出してみて、「ここが足りない」「ここが余計」を調整。

Step 4: チームに共有

repo に commit して、他のメンバーに使ってもらう。フィードバックで更に磨く。

Step 5: 複数スキルで組み合わせる

スキルが 3-5 本溜まってきたら、それらを組み合わせたワークフローを設計。

まとめ

Agent Skills は、エージェントに特定の仕事のやり方を packaged で渡す仕組み
Fine-tuning より軽く、プロンプト使い回しより組織的
SKILL.md の description が最重要 (LLM の選択基準)
1 スキル = 1 ワークフロー、100-300 行が目安
Claude Desktop / Claude Code / Claude.ai で動く
MulmoTerminal / MulmoClaude で複数セル並列実行時に特に有効
チーム共有で組織的な AI 利用の標準化に効く

プロンプトエンジニアリング → コンテキストエンジニアリング → スキルエンジニアリング という進化線上にあります。

Agent Skills とは — 自作スキルで Claude に専門性を注入する実践ガイド