Skills

Skills（スキル）は、AI コーディングエージェントに「うちのやり方」を持たせる仕組みです。プロジェクト固有の流儀・繰り返し作業・社内ルールをファイルとして書いておくと、必要な場面でエージェントが自分でそれを読み込み、毎回説明しなくても同じ手順を再現します。本記事は Anthropic の Claude Skills を軸に、Cursor や GitHub Copilot など他ツールにも共通する考え方を、初学者向けに整理します。

What problem it solves

01「また同じ前置きを書いている」を消す

AI に作業を頼むたび、同じ注意書きを添えていないでしょうか。たとえば次のようなものです。

• 「コミットメッセージは英語で、Conventional Commits 形式（feat: / fix: など）で」
• 「テストは Vitest で、describe / it の階層で書いて」
• 「リファクタの前に、まず影響範囲を一覧化して」

こうした指示はチャットに毎回書いても、会話が終われば消えます。Skill としてファイルに残せば、エージェントは関連する作業のときに自動でその内容を参照します。同じことを教え直す手間が減り、人が変わっても・セッションが変わっても挙動が揃うのが利点です。

02Skill の正体は「フォルダ」

よくある誤解として「Skill ＝ Markdown ファイル 1 枚」と思われがちですが、Claude の Agent Skills では 1 つの Skill ＝ 1 つのフォルダです。フォルダの中心に SKILL.md を置き、必要なら補助ファイル（参照資料・スクリプト）を同梱します。

my-skill/
  SKILL.md          ← 本体（必須）
  references/        ← 詳細な手順・仕様（任意）
    forms.md
  scripts/           ← 実行スクリプト（任意）
    convert.py

SKILL.md の先頭には YAML フロントマターで name と description を必ず書きます。この 2 つはエージェントが起動時に読む「目次」にあたり、特に description が「いつこの Skill を使うか」を決める鍵になります（後述）。

---
name: e2e-test-writer
description: Vitest + Playwright で E2E テストを書くときに使う。ファイル命名・describe 階層・データ後始末の規約を定義する。
---

# 命名
- 1 機能 1 ファイル / ファイル名: feature-name.e2e.ts

# describe 階層
- 最上位: 機能名 / 第 2 階層: ユーザー操作シーケンス
...

03仕組みの肝：プログレッシブ・ディスクロージャ

「Skill をたくさん入れると、毎回全部読み込んでコンテキスト（AI が一度に扱える作業領域）を圧迫するのでは？」——ここを解決するのが 段階的開示（progressive disclosure）という設計です。Skill は 必要になった分だけ、3 段階で読み込まれます。

FIG.1　起動時は「目次」だけ、該当したら本体、さらに要れば補助ファイル——という3段階の読み込み

この設計のおかげで、Skill を多数そろえても起動コストはほぼ増えません。だからこそ「Skill 本体（SKILL.md）は簡潔に保ち、長い詳細は別ファイルへ逃がす」のが定石です（Anthropic は本体の目安として概ね 500 行以内を推奨）。

04使い方（Claude Code の例）

① Skill を置く場所を決める

置き場所で「適用範囲」が変わります。プロジェクト内に置けばチームで共有、ユーザー領域に置けば全プロジェクトで使えます。

プロジェクト用	個人用（全プロジェクト）
.claude/skills/<名前>/SKILL.md	~/.claude/skills/<名前>/SKILL.md
Git でチーム共有。そのリポジトリ固有の流儀向き	自分の手元だけ。言語標準など横断的な好み向き

② 自動発動 ──「呼び出しコマンド」ではなく description で起動する

ここが初学者のつまずきどころです。Skill は基本的に明示コマンドで呼ぶものではなく、エージェントが description を見て「今これが要る」と判断したら自動的に起動します。つまり、起動精度は description の書き方でほぼ決まります。

Skill が効くかどうかは中身より、「いつ使うか」を description にどれだけ正確に書けたかで決まる。

• 悪い例：「テストのスキル」——曖昧で、いつ発動すべきか判断できない。
• 良い例：「Vitest + Playwright で E2E テストを書く／直すときに使う。ファイル命名・describe 階層・データ後始末を定義」——トリガー条件が具体的。

③ チームで共有する

プロジェクト内の Skill は Git でバージョン管理できます。チーム全員が同じ Skill を共有すれば、AI の振る舞いが人によってブレなくなります。さらに近年は、複数の Skill・スラッシュコマンド・MCP 連携などをまとめたプラグインとして配布・導入する流れも一般化しました。Claude Code には Anthropic 公式のマーケットプレイスがあり、/plugin install <名前>@claude-plugins-official のように導入できます（導入前に提供元・README を必ず確認）。

05どんな Skill を作るか

06他ツールでの「Skills 相当」と標準化の流れ

「うちのやり方を設定ファイルに書く」という発想は、いまやどのエージェントにも共通します。名前と方式がツールごとに違うだけです。

ツール	設定の置き方
Claude Code	.claude/skills/<名前>/SKILL.md（タスク単位の Skill）＋ プロジェクト全体は CLAUDE.md
Cursor	.cursor/rules/*.mdc（フロントマターで対象ファイルを絞る glob 指定）
GitHub Copilot	.github/copilot-instructions.md
Codex / Gemini CLI / その他	AGENTS.md（リポジトリ直下の共通ファイル）

2026 年時点の大きな動きは、AGENTS.md が事実上の共通フォーマットになりつつあること。Linux Foundation 配下のオープン標準として、Codex・Cursor・Copilot・Gemini CLI・Aider・Windsurf など多くのツールがそのまま読みます。加えて、タスク単位の SKILL.md 形式も Claude Code に閉じず、Cursor や Copilot（エージェントモード）など複数ツールで読めるようになり、Skill の使い回し（ポータビリティ）が現実的になってきました。

実務的な目安としては、まず AGENTS.md でプロジェクト共通の方針を 1 枚書き、ファイル種別ごとに細かく出し分けたくなったら Cursor の .mdc を足し、Claude Code を主軸にするチームなら CLAUDE.md / Skills を厚くする——という段階導入が無難です。

07Skill を育てる順番

08注意点

• description が全て。 いつ発動すべきかが曖昧だと、必要なときに起動しない／無関係な場面で起動する。最初に磨くべきはここ。
• 本体は薄く、詳細は別ファイルへ。 段階的開示が効くので、長い仕様は references/ に逃がし、SKILL.md は要点だけにする。
• 機密情報を入れない。 Skill は Git に入る前提。秘密鍵・トークン・個人情報は厳禁。値は環境変数やシークレットマネージャ経由で扱う。
• プロジェクト全体に効くものは設定ファイルで十分なことも。 リポジトリ共通の方針なら AGENTS.md や CLAUDE.md に 1 枚書くほうが見通しが良い。タスク単位の手順だけを Skill にする、と棲み分けると整理しやすい。

09まとめ

Skills は、AI を「毎回ゼロから説明する道具」から「うちの流儀を覚えた同僚」へ変える仕組みです。フォルダに SKILL.md を置き、description に「いつ使うか」を正確に書く——たったこれだけで、エージェントは必要な場面で自分から手順を呼び出します。「もう一度説明するのが面倒だな」と感じたら、それが Skill 化のサインです。小さく作り、使いながら育てていきましょう。