Claude Code Skills自作入門｜独自スキルでプロジェクト特化のAI開発環境を構築する手順【2026年版】
こんにちは、株式会社TIMEWELLの濱本です。Claude Codeシリーズも今回で第6弾になりました。
前回までの記事で、公式ビルトインから金融特化スキル、コミュニティ発の尖ったスキルまで、既製のスキルを紹介してきました。ただ、実際に業務で使い込んでいくと、自分の会社やプロジェクトの事情に合わせた「手製のスキル」が欲しくなる瞬間が必ず訪れます。法務レビューの指差し確認、社内特有のコード規約、請求書のフォーマット変換。どれも既製スキルでは痒いところに届かない。
自作スキルの書き方はドキュメントを読めばそれなりに動くものは作れます。ただ、「ちゃんと自動で起動する」「他人にも再利用される」「半年後の自分でも読める」レベルに持っていくには、いくつかコツが要ります。2026年4月時点で蓄積された知見をもとに、SKILL.mdの作法から組織共有の運用まで、実例を交えてまとめます。
Skillsが便利な理由とCLAUDE.mdとの使い分け
Skillsを語る前に、そもそもCLAUDE.mdと何が違うのかをはっきりさせておきたいです。ここが曖昧なまま書き始めると、結局「CLAUDE.mdでよくない？」という結論に落ちがちなので。
CLAUDE.mdはプロジェクトの恒常的なコンテキストを記述する場所で、セッション開始時に毎回システムプロンプトに注入されます。コーディング規約、ドメイン用語、禁止事項などを入れておけば、Claudeが常に踏まえて回答してくれる。便利なのですが、肥大化すると読み込みコストも上がるし、あらゆるタスクに関係ない情報までロードされて精度が落ちる。2025年後半から「CLAUDE.mdが太りすぎる問題」として議論になっていた話です。
Skillsはこの問題を綺麗に解きます。.claude/skills/{skill-name}/SKILL.md というフォルダ構造にスキルを置いておくと、Claudeは起動時にSKILL.mdのfrontmatterにあるnameとdescriptionだけをスキャンし、全体像を把握します。ここでコンテキストに載るのは1スキルあたり約100トークン。数十個のスキルを抱えていても、ほぼ無視できるコストです。そして対話の流れの中で「あ、このタスクはこのスキルが要るな」とClaudeが判断した瞬間に、該当スキルのSKILL.md本文（5,000トークン以内が推奨）が読み込まれ、さらに付属スクリプトやテンプレートは実行時に初めてロードされる。プログレッシブディスクロージャ（段階的開示）と呼ばれる設計です。
結果として、CLAUDE.mdには「プロジェクト全体で常に守るべき事項」だけを残し、個別の作業手順はすべてSkillsに切り出すのが正しい住み分けになります。筆者の感覚では、CLAUDE.mdの半分以上はSkillsに移せます。実際、TIMEWELLのこのサイト（timewell.jp）でも、コラム執筆の詳細手順は article-writing スキルに切り出していて、CLAUDE.mdには「記事を書くときはarticle-writingスキルを通すこと」という1行しか残していません。見通しが劇的に良くなりました。
もう一つ、Skillsの大きな利点が同じSKILL.md形式がClaude Code以外でも通用することです。2026年時点で、Cursor、Gemini CLI、Codex CLI、AntigravityなどがSKILL.md互換のスキル読み込みをサポートしており、一度書いたスキルを複数のAIコーディング環境で使い回せます。ベンダーロックインを気にせず投資できるのは精神的にラクです。
SKILL.mdの書き方とfrontmatter設計
自作スキルの心臓部はSKILL.mdの先頭にあるYAMLのfrontmatterです。ここが雑だとスキルは自動起動せず、結局/スキル名 で明示呼び出ししないと動かない置き物になります。
必須フィールドは2つだけ。nameとdescriptionです。シンプルですが、この2行の設計だけで成否の8割が決まります。
---
name: sql-migration-reviewer
description: Use when reviewing SQL migration files before deployment. Checks for destructive operations (DROP, TRUNCATE), missing indexes on foreign keys, and forgotten rollback scripts. Triggers on keywords "migration", "schema change", "ALTER TABLE", or when the user asks to review .sql files in db/migrations/.
---
nameはスラッシュコマンドとしても使われるので、英小文字とハイフンで、職能を1語で表す名前にします。動詞＋対象の組み合わせが読みやすい。review-sql-migration より sql-migration-reviewer のように名詞化した方が、自分が忘れた頃に見返したときに意味がわかります。
そしてdescription。ここが真の主戦場です。Anthropic公式のSkill authoring best practicesでも強調されているとおり、descriptionは単なる説明ではなくトリガーとして機能します。Claudeは起動時に全スキルのdescriptionをスキャンし、ユーザーの発話とマッチするものだけを候補に残す。つまりdescriptionに書かれていない状況では、そのスキルは永遠に呼ばれないということです。
ここで効くのが命令形と具体的なトリガー語の列挙です。Ivan Seleznov氏が650回のトライアルで活性化率を測った記事[^1]によると、「Helps you review code」のような受動態の説明だと起動率77%なのに対し、「ALWAYS invoke this skill when reviewing any code changes before committing. DO NOT write security feedback without invoking this skill first」のように命令形＋否定制約で書くと100%に跳ね上がったとのこと。Claudeも人間と同じで、曖昧に言われたことより強く指示されたことを優先する、ということでしょう。
もう一つの鉄則は三人称で書くこと。「You should use this when...」のような二人称は、システムプロンプトに注入されるときに主語が揺れて発見に失敗するケースが報告されています。「Use when...」「Triggers when...」のような命令形か、「This skill reviews...」のような三人称単数が無難です。
本文（Markdown部分）の書き方は、Anthropic公式のskill-creatorが推奨するスタイルに従うと外れません。要点は4つです。第一に手順を番号付きで書くこと。第二に「直接命令」の文体で書くこと（「Extract the color palette」であって「You should extract...」ではない）。第三に具体例を含めること。第四に失敗パターンと回避策をセットで書くこと。あれこれ美文にしようとせず、コマンドを羅列する感覚で書くのが正解です。
実装例：コードレビュースキルと議事録整形スキル
抽象論ばかりだと手が動かないので、実際に動くスキルを2つお見せします。どちらもプロジェクト直下の .claude/skills/{skill-name}/SKILL.md に置けばすぐ使えるものです。
例1：PRセキュリティレビュースキル
社内規約として「コミット前にセキュリティ観点でDIFFを必ず見る」というルールを運用しているチーム向けのスキルです。
---
name: pr-security-review
description: ALWAYS invoke this skill before the user runs `git commit` or `git push`. Use when reviewing staged changes, PR diffs, or when the user says "レビューして" "check the diff" "before I push". DO NOT write a commit message without invoking this skill first. Checks for hardcoded credentials, SQL injection risks, XSS vectors, missing input validation, and exposed debug endpoints.
---
# PR Security Review
ステージされた変更をセキュリティ観点でレビューする。
## 手順
1. `git diff --staged` で変更差分を取得
2. 以下7項目を順番にチェックする
- ハードコードされた認証情報（API key, password, token）
- SQLインジェクションの余地（文字列結合でのクエリ生成）
- XSSの余地（innerHTML, dangerouslySetInnerHTML への未エスケープ値）
- 認可チェック漏れ（APIルートの先頭でsession/user確認があるか）
- 入力バリデーション漏れ（zod, joi 等のスキーマ検証の有無）
- デバッグエンドポイントの残留（/debug, /admin/test 等）
- 秘匿ログの流出（console.log でトークンや個人情報を出力）
3. 問題があれば該当ファイルと行番号を引用して指摘
4. 問題がなければ「セキュリティ観点での懸念は見つからなかった」と明示
5. その後、通常のコミットメッセージ作成プロセスに戻る
## 出力フォーマット
指摘がある場合のみ、以下のMarkdown形式で返す。
| 重大度 | ファイル:行 | 問題 | 推奨対応 |
|---|---|---|---|
| High | src/api/login.ts:42 | パスワードを平文でログ出力 | ログ出力を削除 |
## やってはいけないこと
- 「おそらく問題ありません」のような曖昧な判定
- 憶測での指摘（該当コードが存在することを必ず引用して示す）
descriptionで git commit git push レビューして のような具体的な引き金を並べているのがポイントです。こうすると、ユーザーが自然な会話で「そろそろpushするわ」と言った瞬間にClaudeが自動でスキルを起動します。
例2：議事録整形スキル
エンジニアリング以外の用途でも、Skillsはそのまま使えます。たとえばチームミーティングの文字起こしを決まったフォーマットに整形するスキル。
---
name: meeting-notes-formatter
description: Use when the user pastes raw meeting transcripts, Zoom auto-captions, or otter.ai exports. Triggers on keywords "議事録" "文字起こし" "meeting notes" "整形して" or when the user provides text over 1000 characters that contains timestamps like [10:15]. Converts raw transcripts into structured minutes with decisions, action items, and open questions.
---
# Meeting Notes Formatter
生の文字起こしを構造化された議事録に変換する。
## 入力想定
Zoom / Google Meet / otter.ai の自動文字起こし、または手動メモ。
タイムスタンプ・発話者名・雑談・相槌が混じっている前提。
## 変換ルール
1. 相槌（「はい」「なるほど」「ええ」）をすべて削除
2. 発話者名を `**名前：**` 形式に統一
3. 以下3セクションを必ず作成する
- Decisions（決定事項）
- Action Items（担当者と期限が明確なタスク）
- Open Questions（未解決の論点）
4. Action Itemsは `- [ ] {担当者}: {内容}（期限：{YYYY-MM-DD}）` 形式
5. 10分ごとの時刻見出しを `## 10:00-10:10` の形で入れる
## 禁止事項
- 原文にない決定事項を創作しない
- 発言を意訳しすぎない（固有名詞・数字は原文通りに）
- 雑談部分を「雑談」として残すか完全削除するかは、本文先頭で宣言する
この2つはTIMEWELLの社内でも似たものを運用しています。議事録整形スキルは、週次のプロダクト定例で毎回使うことで、議事録の作成時間が従来の25分から5分に短縮されました。地味ですが、年間にすると馬鹿にならない差になります。
より体系的なスキル集を参考にしたい場合は、Claude Code Skills 45選でビルトインやコミュニティ製の実例をまとめているので合わせて読んでみてください。
組織全体でスキルを共有する方法
自作スキルがチームの資産として機能し始めるのは、個人フォルダから外に出した瞬間です。ここの運用設計を怠ると、せっかく作ったスキルがその人の ~/.claude/skills/ に塩漬けになります。
配置場所は3階層あります。~/.claude/skills/ はユーザースキルで、自分専用。.claude/skills/ はプロジェクトスキルで、そのリポジトリをcloneした人全員が使える。そして2026年時点で新しく整備されたのがTeam・Enterpriseプランの組織スキルで、organization settingsから一括配布できます。個人で試作したものをプロジェクトに昇格させ、最終的に全社標準へ採用する、という3段階で昇格させていくのが健全な運用だと感じています。
もっとも現実的でハードルが低いのは、プロジェクトスキルとしてGitHubにコミットする方法です。たとえば次のような構造でリポジトリを管理します。
my-project/
├── .claude/
│ ├── settings.json
│ └── skills/
│ ├── pr-security-review/
│ │ └── SKILL.md
│ ├── sql-migration-reviewer/
│ │ └── SKILL.md
│ └── meeting-notes-formatter/
│ └── SKILL.md
├── src/
└── CLAUDE.md
これをリポジトリに入れておけば、新しく参画したメンバーがclone＋claude を起動した瞬間から、チーム共通のスキルが全員に適用されます。オンボーディングコストが劇的に下がる仕組みです。
有名なOSSプロジェクト obra/superpowers は、この思想を全面的に推し進めたフレームワークです。brainstorming、writing-plans、using-git-worktrees、subagent-driven-development、systematic-debugging など15以上のスキルが含まれ、ソフトウェア開発の全工程にわたる方法論が1つのプラグインに整理されています。/plugin install superpowers@claude-plugins-official でインストールでき、筆者もサブエージェント駆動開発を試す用途で入れっぱなしにしています。導入手順や使い分けはSuperpowersプラグイン徹底解説で詳しく書いたので参考にしてください。
Team・Enterpriseプランを契約している組織では、さらに強力な配布機能が使えます。Admin権限のあるメンバーがorganization settingsのSkillsタブからスキルをアップロードすると、組織内の全ユーザーが自動的にそのスキルを Personal / Shared / Organization の3セクションのうちOrganization側で受け取ります。個人で無効化もできるので、強制ではなく「デフォルト有効な社内標準」という位置づけ。さらにenterprise managed settingsを併用すれば、特定のスキルを強制適用することも可能です。法務レビュー必須、禁止ワードチェック必須のような運用に向いています[^2]。
共有運用でもう一つ考えたいのがバージョン管理です。スキルの中身は頻繁にアップデートされるので、SKILL.mdの末尾に ## Changelog セクションを設けて変更履歴を残しておくと、半年後のデバッグで効きます。筆者はGit tagで skill-vX.Y.Z を打つ運用にしています。
失敗パターンと運用の勘所
自作スキルを1年近く運用してきて、やらかしたことも含めて共有すべき失敗パターンがいくつかあります。先に知っておくと数時間の無駄を避けられます。
もっとも多い失敗が自動起動しないスキルです。気合を入れて中身を書いたのに、何度会話してもClaudeがスキルを呼び出してくれない。理由のほぼすべてはdescriptionです。「Helps with code review」のような一般的すぎる説明だと、類似スキルと競合して起動判断が割れる。先述のとおり命令形にして、具体的なキーワードや状況を列挙するのが効きます。それでも呼ばれないときは、一度/list-skills で候補に出ているかを確認し、出ているのにトリガーしないならdescriptionの曖昧さを疑う、という切り分け手順を習慣にしてください。
次に多いのがmega-skill問題。何でもできるように詰め込みすぎて、結局どの状況でも中途半端に動くスキルです。Anthropic公式が何度も強調しているとおり、1スキル＝1責務が原則です。「コードレビューもドキュメント生成もテスト作成もするスキル」は、それぞれ別スキルに分けた方が精度も高く、再利用もしやすい。筆者も最初は「開発支援スキル」という巨大なものを作ってしまい、3ヶ月後に3つに分割した苦い経験があります。
3つ目はテストプロンプトが綺麗すぎる問題。スキルを書いた本人は「このスキルはこう使うはず」という理想のユーザー発話を思い浮かべて動作確認しがちです。ただ、実際のチームメンバーはもっと雑な言い方をする。「ちょっと見て」「これ大丈夫？」「さっきのDIFFの件」のような省略表現で呼んでくる。UX Planetの記事[^3]でも指摘されていますが、テストプロンプトは実際のSlack会話を参考にして、省略・タイポ・口語を混ぜた形で書くのが正しい検証方法です。
最後に、運用が定着し始めてから効いてくるのがCLAUDE.mdとの役割分担です。繰り返しになりますが、CLAUDE.mdには「プロジェクト全体で常に守る事項」だけを残し、個別作業手順はSkillsに切り出す。この分離を徹底するだけで、コンテキスト効率も精度も上がります。
こうした運用設計は、一人のエンジニアが片手間でやるには少し骨が折れます。社内のSOP（標準作業手順）をスキル化して全社展開したい、あるいは業界特有のコンプライアンス要件をスキルに落とし込みたいといったケースでは、外部の知見を借りるのも現実的な選択肢です。TIMEWELLのAIコンサルティングサービス WARP では、Claude CodeやClaude Agent SDKを活用した社内業務のスキル化設計を支援しています。社内ナレッジを一次情報としてAIに使わせたい場合は、GraphRAG基盤の ZEROCK と組み合わせることで、Skillsが参照する社内データ層まで含めた仕組みを整えられます。
Skillsの考え方や実装パターンをもっと深く知りたい方は、Claude Codeエージェントチーム構築ガイドもあわせて読んでいただくと、スキル＋サブエージェントの組み合わせ方まで視野が広がるはずです。
まとめ
Claude Code Skillsは、CLAUDE.mdという万能ポケットが肥大化する問題をエレガントに解きました。プロジェクト固有のやり方、社内規約、業界特有の判断基準といった「毎回使うわけではないが、特定の場面では絶対に使いたい知識」を、コンテキスト効率を落とさずに差し込める仕組みです。
自作する上でもっとも大事なのは、SKILL.mdのdescriptionを命令形＋トリガー語の列挙で書くこと。ここさえ外さなければ、スキルはちゃんと自動起動します。あとは1スキル＝1責務を守り、GitHubリポジトリに入れてチームで共有していけば、半年後には「昔どうやって仕事してたっけ」と思えるくらい開発体験が変わります。
まずは自分が週に3回以上やっている定型作業を1つ選んで、SKILL.md 1枚書いてみてください。1時間で作れて、翌日から効果が出ます。筆者のおすすめはPRレビュースキル。効果を実感しやすく、チームにも展開しやすい入門ネタです。
[^1]: Ivan Seleznov, "Why Claude Code Skills Don't Activate (650 Trials)," Medium, 2026. https://medium.com/@ivan.seleznov1/why-claude-code-skills-dont-activate-and-how-to-fix-it-86f679409af1 [^2]: Anthropic, "Provision and manage Skills for your organization," Claude Help Center, 2026. https://support.claude.com/en/articles/13119606-provision-and-manage-skills-for-your-organization [^3]: Nick Babich, "7 Rules for Creating an Effective Claude Code Skill," UX Planet, April 2026. https://uxplanet.org/7-rules-for-creating-an-effective-claude-code-skill-2d81f61fc7cd