業務手順をAIに記憶させる仕組み
Skillsは、Claude Codeに再利用可能な業務手順やドメイン知識を記憶させる仕組みです。.claude/skills/<name>/SKILL.mdというMarkdownファイルに業務手順を定義しておくと、 ユーザーが/skill-nameで呼び出すか、Claudeが文脈に応じて自動的に呼び出してくれます。
たとえば「毎回同じ手順でレポートを生成する」「特定のフォーマットでコードレビューをする」といった繰り返し業務があるなら、 その手順をSkillとして定義しておけば、次回からは一言の指示で同じ品質の作業を再現できます。
ポイント: Skillsの最大の特徴は「Claudeが自動で呼び出せる」ことです。 ユーザーが明示的にコマンドを叩かなくても、Claudeが会話の文脈から「このSkillを使うべきだ」と判断すれば自動的に適用されます。
Skillsには大きく分けて2つの使い方があります。目的に応じて使い分けることで、より効率的なワークフローを構築できます。
/skill-nameまたはSkill toolで直接呼び出す方式です。 独立した処理タスク（レポート生成、コード品質チェックなど）に向いています。 会話のコンテキストからデータを受け取り、結果を返します。
Agentのskills:フィールドで指定し、ドメイン知識としてAgent内に注入する方式です。 Agentが起動した時点でSkillの内容がコンテキストに読み込まれ、エージェントの「知識」として機能します。
このパターンではuser-invocable: falseを設定するのが一般的です。 これにより、/メニューに表示されなくなり、バックグラウンド知識としてのみ機能します。
---
name: api-guidelines
description: API設計のガイドラインとベストプラクティス
user-invocable: false
---
# API設計ガイドライン
## 命名規則
- エンドポイントはケバブケースを使用
- リソース名は複数形
...SKILL.mdはYAMLフロントマターとMarkdown本文で構成されます。 フロントマターには13個のフィールドがあり、Skillの動作を細かく制御できます。
---
name: my-skill
description: このSkillが何をするかの説明
disable-model-invocation: false
user-invocable: true
allowed-tools: Edit, Read, Bash
model: sonnet
effort: medium
context: fork
agent: general-purpose
paths: "src/**/*.ts"
hooks: {}
argument-hint: "対象ファイルのパス"
shell: bash
---
# Skill本文
ここに具体的な手順や知識を記述します。各フィールドの役割は以下のとおりです。
trueにするとClaude自動呼び出しを防止falseで/メニューから非表示にするforkで分離サブエージェントコンテキストで実行context: fork時に使用するサブエージェントタイプ/メニューに表示される引数のヒントClaude Codeには最初から使える公式Skillsが5つ同梱されています。 これらは日常的な開発作業ですぐに活用できます。
SKILL.mdの本文にすべての情報を詰め込むと、コンテキストを圧迫してしまいます。 そこで有効なのがProgressive Disclosure（段階的開示）パターンです。
SKILL.md本文には核心となる手順だけを書き、詳細な情報はサブディレクトリに分けて配置します。 Claudeは必要に応じてこれらのファイルを参照します。
.claude/skills/my-skill/
SKILL.md # 核心の手順のみ
references/ # 参照ドキュメント
api-spec.md
schema.md
scripts/ # 補助スクリプト
setup.sh
validate.py
examples/ # 実例
good-example.md
bad-example.mdこの構造にすることで、SKILL.md自体は軽量に保ちつつ、Claudeが深掘りする際には十分な情報を提供できます。
Skillを運用していると、必ず「うまくいかないパターン」が出てきます。 Anthropicの共同創業者であるThariq氏は、Skillの中に失敗パターンを蓄積する「Gotchas」セクションを設けることを強く推奨しています。
私の経験でも、このGotchasセクションはSkillの中で最も価値の高いコンテンツになります。 「このAPIを呼ぶときは必ずヘッダーにX-Request-IDを含めること」 「日付フォーマットはISO 8601でないとバリデーションエラーになる」 ――こうした具体的な落とし穴を記録しておくことで、同じミスの繰り返しを防げます。
## Gotchas（よくある落とし穴）
- レスポンスのページネーションは必ず処理すること。
デフォルトでは最初の20件しか返らない
- 環境変数 API_KEY が未設定だとサイレントに失敗する。
必ず起動時にチェックを入れること
- タイムゾーンはUTCで統一。JSTで計算すると
日付境界でバグが発生する効果的なSkillを作るためのポイントをまとめます。
descriptionフィールドは「このSkillはいつ発動すべきか？」というトリガー条件として機能します。 「何をするか」よりも「いつ使うべきか」を明確に書くことで、Claudeの自動呼び出し精度が上がります。
# 良い例
description: "TypeScriptのテストファイルを作成・更新するとき"
# 悪い例
description: "テストユーティリティ"Claudeが既に知っている一般的な知識をSkillに書く必要はありません。 プロジェクト固有のルールや、ドキュメントに載っていない暗黙知こそがSkillに書くべき内容です。
「ステップ1でこれをやり、ステップ2でこれをやり...」と細かく手順を指定するよりも、 達成すべきゴールと守るべき制約を示す方が、Claudeは柔軟に対応できます。
繰り返し使うシェルスクリプトやPythonスクリプトは、Skill内のscripts/ディレクトリに配置します。 Claudeがこれらを直接実行できるため、毎回同じコードを生成する無駄を省けます。
SKILL.md内で!`command`記法を使うと、シェルコマンドの実行結果をプロンプトに動的に注入できます。 これにより、実行時の環境情報をSkillに反映させることが可能です。
現在のブランチ: !`git branch --show-current`
変更ファイル一覧:
!`git diff --name-only`context: forkを設定すると、Skillがメインの会話コンテキストとは別の分離された環境で実行されます。 これは以下のような場面で有効です。
---
name: heavy-analysis
description: 大規模なコード分析を実行
context: fork
agent: general-purpose
---
# 分析手順
この Skill は分離コンテキストで実行されるため、
メインの会話には結果のサマリーだけが返されます。Anthropic社のThariqが公開した分類によると、 実務で効果的なSkillは9つのカテゴリに整理できます。 「どんなSkillを作るべきか」を考えるとき、このフレームワークが役立ちます。
社内ライブラリやClaude Codeが苦手なライブラリの正しい使い方を教えるSkill。 リファレンスコードやよくある間違い（Gotchas）を含めます。
コードが正しく動作しているかを検証する方法を定義するSkill。 PlaywrightやtmuxなどのExternal Toolと組み合わせます。 Thariq曰く「作り込む価値が最も高いカテゴリ」です。
データベースや監視ツールに接続し、分析ワークフローを定義するSkill。 認証情報の注入方法、よく使うクエリ、ダッシュボードIDなどを含めます。
スタンダップ投稿、チケット作成、週次レポートなど、 繰り返しのビジネスワークフローを1コマンドにするSkill。 前回の結果をログファイルに保存し、一貫性を保ちます。
フレームワーク固有のボイラープレートを自動生成するSkill。 コード生成と自然言語の要件定義を組み合わせます。
コードスタイルの強制やレビュー観点を定義するSkill。 決定論的なスクリプト（linter等）と組み合わせると効果的です。 HooksやGitHub Actionで自動実行することもできます。
ビルド・テスト・デプロイのワークフローを定義するSkill。 他のSkillを参照してデータを収集する複合型になることもあります。
障害対応の手順書をSkill化したもの。 Slackスレッドやアラートをインプットに、マルチツール調査を行い、構造化レポートを出力します。
リソースの棚卸し、依存関係管理、コスト調査など、 ルーティンのインフラ保守作業をSkill化したもの。 破壊的操作を含む場合はガードレールを組み込みます。
ポイント: この9カテゴリは「Skillで何ができるか」を考えるためのフレームワークです。 まずは自分の業務を振り返り、どのカテゴリに当てはまるかを考えてみてください。 最も作り込む価値が高いのは「プロダクト検証」と「ライブラリリファレンス」です。
Claude Codeには5つのビルトインSkillが最初から組み込まれています。 インストール不要で、すぐに使い始められます。
/simplify — 変更したコードのリファクタリング。重複排除、品質改善、効率化を自動で行います。 コードを書いた直後に実行すると、見落としていた改善点を指摘してくれます。/batch — 複数ファイルに対して一括操作を実行。大規模なマイグレーションやリネーム作業で 数十〜数百のファイルを並列処理できます。/debug — 失敗したコマンドやコードの問題をデバッグ。エラーメッセージを自動分析し、 原因と修正案を提示します。/loop — プロンプトやSkillを定期的に繰り返し実行。 詳しくは「定期実行とスケジュール」ページで解説します。/claude-api — Claude APIやAnthropic SDKを使ったアプリケーション開発を支援。 コードにimport anthropicが含まれると自動で発動します。作成したSkillを他のプロジェクトやチームメンバーに共有する方法は2つあります。
.claude/skills/ディレクトリをgitで管理。 小規模チーム、少数リポジトリの場合に最適です。Skillの利用状況を計測するには、PreToolUseフックでSkill呼び出しをログに記録します。 これにより、どのSkillがよく使われているか、期待に反して使われていないSkillはどれかを把握できます。
Skillsは、Claude Codeの中でも特に実用性の高い機能です。 繰り返し行う業務手順をSKILL.mdに定義しておけば、品質のばらつきを抑えながら作業を効率化できます。 9つのカテゴリを参考に、まずは日常的に繰り返している作業を1つ選び、Skillとして定義してみてください。 Progressive Disclosureで情報を段階的に整理し、Gotchasセクションで失敗パターンを蓄積していけば、 Skillは使うほどに価値が高まっていきます。