SKILL.mdでClaude Codeのワークフローを自動化する実践ガイド ── superpowers 15万Starの設計思想

Posted at 2026-04-13

Claude CodeにおけるSkillsとは何か

Claude Codeを使い込んでいくと、毎回同じ指示を繰り返している自分に気づきます。「記事を書くときはまずWeb検索して、構成案を出して、承認を得てから執筆して、output/articles/に保存して」。こうした定型ワークフローを再利用可能な形で切り出し、AIエージェントに「手順ごと」覚えさせる仕組みが Skills（Agent Skills）です。

Anthropicが2025年10月に公式にAgent Skillsを発表して以降、Claude Codeの拡張性は「コンテキストをどう詰め込むか」から「いつ、どの手順を読み込ませるか」という設計論に移りました。Skillsは「特定タスクの手順書」であり、必要になった瞬間だけロードされます。常時読み込まれるCLAUDE.mdと似た概念ですが、役割は明確に異なります。

概念	配置場所	役割	粒度
CLAUDE.md	プロジェクトルート	プロジェクト全体のルール・方針・制約	広い（常に適用）
SKILL.md	`.claude/skills/<skill名>/` または `.claude/commands/`	特定タスクの実行手順・ワークフロー定義	狭い（呼び出し時のみ適用）
`.claude/agents/*.md`	`.claude/agents/`	サブエージェントの役割・振る舞い定義（個別のMarkdownファイル群）	中間（委譲時に適用）

CLAUDE.mdが「このチームではTypeScriptを使い、テストカバレッジ80%以上を維持する」といったルールを定めるのに対し、SKILL.mdは「PRレビューを実行するとき、まずdiffを取得し、次にセキュリティ観点でチェックし、最後にコメントを投稿する」という具体的な作業手順を記述します。前者は「憲法」、後者は「業務マニュアル」と考えると整理しやすいです。

なぜCLAUDE.mdとSKILL.mdを分けるのか

この2つを分ける理由は、コンテキストウィンドウの経済性にあります。CLAUDE.mdに全ての手順書を詰め込むと、無関係なタスクでも毎回全文が読み込まれ、モデルの注意が散漫になります。Anthropicが公式ドキュメントで Progressive Disclosure（段階的開示）と呼ぶ設計原則はここに対応していて、初期コンテキストにはSkillsのfrontmatter（名前と説明）だけを載せ、Claudeがタスクを見て「これが使えそうだ」と判断した瞬間にSKILL.mdの本体を読み込みます。さらに必要なら参照ファイルやスクリプトを追加ロードしていく、という3段階構造です。

つまりSkillsは「使うときだけ広がる折りたたみ式のマニュアル」です。手順が100個あっても、今のタスクに関係する1個だけが展開されるため、コンテキスト消費は最小限で済みます。

MCPとの違いと使い分け判断基準

MCP（Model Context Protocol）は外部ツールとの接続層です。GitHub API、Google Calendar、データベースなど、Claude Codeが「何にアクセスできるか」を定義します。一方Skillsは「アクセスできるツールをどう組み合わせて使うか」を定義します。MCPが道具箱なら、Skillsはその道具を使ったレシピです。

判断に迷ったときは次の基準が使えます。

外部サービスとの通信、認証、API呼び出しが必要 → MCP
手順の定型化、判断基準の明文化、成果物フォーマットの固定 → Skills
両方必要なら、MCPで接続を確立した上で、Skillsがその呼び出し順序を定義する

実務では「MCPで繋いだSlackに、Skillsで定義した定型フォーマットで投稿する」といった組み合わせが典型です。

superpowersが15万Starに達した背景

superpowersはJesse Vincent（GitHub: obra）が2025年10月に公開したClaude Code向けのSkillsフレームワークです。Jesse VincentはPerlのRequest Tracker（RT）の作者でPerl 5の pumpking も務めた人物で、Keyboardio の共同創業者としても知られています。superpowersは公開から半年ほどで約15万Star（2026年4月時点で148,000 Star超）を獲得し、Anthropicの公式プラグインマーケットプレイスにも採用されました。1日あたり数千Starを積み上げる時期もあった急成長プロジェクトで、Claude Codeエコシステムで最も影響力のあるリポジトリと言って差し支えありません。

急成長の核心は、単なるプロンプト集ではなく「7フェーズの開発方法論」をSkillsとして実装したことです。

Brainstorm ── アイデアを発散させ、複数のアプローチを比較検討する
Spec ── 要件を構造化し、成功基準を明文化する
Plan ── 実装計画を作成し、ファイル単位の変更内容を定義する
TDD ── テストを先に書き、実装の完了条件を明確にする
Subagent Dev ── 独立したタスクをサブエージェントに並列実行させる
Review ── コードレビューを実行し、品質基準を満たすか検証する
Finalize ── ブランチ統合、ドキュメント更新、リリース準備を行う

この7フェーズがなぜ有効なのか、理由は2つあります。1つめは、フェーズ間にレビューチェックポイントがあるため、AIが「それらしく書いたが間違っているコード」を生成しても、次のフェーズに進む前に人間が止められる構造になっていることです。2つめは、各フェーズが独立したSKILLとして切り出されているため、TDDだけ、Planだけ、といった部分採用ができることです。この疎結合性が、既存プロジェクトへの段階的導入を可能にしました。

もう一つの文脈として、Mitchell Hashimotoが提唱する「harness engineering（ハーネス工学）」という考え方があります。エージェントが同じミスを繰り返さないよう、検証スクリプトやlintルールをSkillsとして蓄積し、セッションを重ねるほどエージェントが賢くなっていく仕組みを指します。superpowersはこの思想を方法論レベルで実装したフレームワークと位置づけられます。

SKILL.mdの構造を詳細解説

Anthropic公式仕様では、SKILL.mdは必ずYAML frontmatterで始まります。frontmatterには name（スキル名）と description（いつ使うか）が必須で、この2つだけが初期コンテキストにロードされます。したがって description は「何をするか」だけでなく「いつ使うべきか」まで書くのがベストプラクティスです。

---
name: write-draft
description: 記事のテーマを受け取り、リサーチ→構成案→下書きの順で記事ドラフトを生成し output/articles/ に保存する。「記事を書いて」「下書き」等で発火。
---

# write-draft: 記事下書き生成

（本体の手順）

本体に書く要素は次のとおりです。

スキルの目的と前提条件
引数の定義（$ARGUMENTS）
実行手順（ステップバイステップ）
出力フォーマット（期待する成果物の形式）
品質基準・注意事項・人間の判断が必要なポイント

ここからは、実務で使える具体的な全文例を3つ示します。

例1: 記事執筆スキル

---
name: write-draft
description: 記事のテーマから下書きを生成して output/articles/ に保存する。「記事を書いて」「下書きして」で発火
---

# write-draft: 記事下書き生成

## 引数

$ARGUMENTS -- 記事のテーマ・キーワード・方向性

## 実行手順

1. テーマの確認と深掘り
   - ユーザーの指定テーマを確認
   - ターゲット読者、記事の目的、文字数の目安を確認（不明な場合はユーザーに質問）

2. リサーチ
   - Web検索で関連情報を収集
   - 00_context/memories/ から関連するメモリを参照
   - 既存記事（output/articles/）と重複がないか確認

3. 構成案を作成
   - タイトル案を3パターン提示
   - 見出し構成（H2/H3レベル）
   - 各セクションの概要
   - ユーザーに構成案を提示して承認を得る（← 人間の判断ポイント）

4. 下書きを執筆
   - 承認された構成に沿って執筆
   - 具体例・データを盛り込む

5. output/articles/ に保存
   - ファイル名: `YYYY-MM-DD-[テーマのスラグ]-draft.md`

6. ユーザーに報告
   - 保存先パス、文字数、レビューポイント

## 注意事項

- 公開前に必ずユーザーの最終確認を取る
- AIが書いたことが明白な表現を避ける

このスキルのポイントは、手順3でユーザーの承認を明示的に挟んでいることです。自動化と人間の判断のバランスを取る設計になっています。

例2: コードレビュースキル

---
name: code-review
description: PR番号を受け取り、diffを5軸でレビューしてPRコメントを投稿する。「PRレビューして」「コードレビュー」で発火
---

# code-review: PRレビュー自動実行

## 引数

$ARGUMENTS -- PR番号またはURL

## 実行手順

1. PR情報を取得: `gh pr view $PR_NUMBER --json` でdiff、変更ファイル一覧、PR説明を取得
2. 変更の分類: 各ファイルの変更を以下に分類
   - 新機能追加 / バグ修正 / リファクタリング / テスト / ドキュメント
3. 5軸レビューを実行
   - セキュリティ: SQLインジェクション、XSS、認証漏れ、秘密情報の混入
   - パフォーマンス: N+1クエリ、不要なループ、メモリリーク
   - 保守性: 命名規則、関数の長さ、責務の分離
   - テスト: カバレッジ、エッジケース、テストの可読性
   - 破壊的変更: API互換性、マイグレーション、依存関係
4. リスクスコアを算出: 各軸を1-5で評価し、総合スコアを算出
5. PRにコメントを投稿: `gh pr comment` でレビュー結果を投稿

## 出力フォーマット

| 軸 | スコア | 指摘事項 |
|----|--------|---------|
| セキュリティ | 4/5 | 問題なし |
| パフォーマンス | 2/5 | N+1クエリの可能性（該当行を示す） |

## 品質基準

- 指摘にはすべて該当コードの行番号を含める
- 修正案を具体的に示す（「改善してください」だけで終わらない）
- 重大な問題はBlockingとして明示する

例3: デプロイスキル

---
name: deploy
description: 指定環境（staging/production）にデプロイし、ヘルスチェックまで完了する。「デプロイして」で発火
---

# deploy: ステージング/本番デプロイ

## 引数

$ARGUMENTS -- デプロイ先環境（staging / production）

## 前提条件

- mainブランチが最新であること
- CIが全てパスしていること

## 実行手順

1. 環境の確認: $ARGUMENTS が staging か production かを判定
2. デプロイ前チェック
   - `gh run list --branch main` でCI状態を確認
   - production の場合、最終確認をユーザーに求める（← 人間の判断ポイント）
3. デプロイ実行
   - staging: `vercel deploy --prebuilt`
   - production: `vercel deploy --prod --prebuilt`
4. ヘルスチェック
   - デプロイURLに対してHTTPリクエストを送信
   - ステータスコード200を確認
   - レスポンスタイムが3秒以内であることを確認
5. 結果報告
   - デプロイURL、ビルド時間、ヘルスチェック結果をユーザーに報告
   - 失敗した場合はロールバック手順を提示

## 注意事項

- production デプロイは必ずユーザーの明示的な承認を得てから実行する
- 深夜・休日のデプロイは避けるよう警告を出す

3つの例に共通する設計原則があります。(1) 手順が具体的で曖昧さがない、(2) 出力フォーマットが明示されている、(3) 人間の判断が必要なポイントが明確にマークされている、の3点です。とくに(3)は、取り消しが困難な操作（本番デプロイ、外部公開、課金操作）で必須の設計です。

CLAUDE.md / AGENTS.md / SKILL.md / MCPの関係整理

4つの概念の関係を図で整理します。

データの流れは次のとおりです。

CLAUDE.md はすべてのスキル・エージェントに対して常に適用されるルールです。「です/ます調で書く」「テストカバレッジ80%以上」といったルールは、どのスキルが実行されても遵守されます
SKILL.md はユーザーの指示をトリガーに呼び出されるエントリーポイントです。内部でサブエージェント（AGENTS.md）に作業を委譲したり、MCP経由で外部ツールを呼び出したりします
AGENTS.md はサブエージェントの専門性と振る舞いを定義します。役割を明確にすることでサブエージェントの出力品質を高められます
MCP はClaude Codeが利用できる外部ツールの接続定義です。Skills内の手順で「Web検索する」「GitHub Issueを作成する」と書けば、対応するMCPツールが自動的に使われます

デザインシステムをSkillsにするアプローチ

Zennの記事「Claude CodeのCustom Slash Commandsでデザインシステムを丸ごとAIに教え込む」で紹介されているアプローチは、Skillsの活用事例として示唆に富んでいます。サイボウズをはじめとする大規模開発チームが同様のアプローチを採用しており、Skillsが「チーム知識のコード化」という役割を担い始めていることが見て取れます。

デザインシステムは本来、人間のデザイナーやフロントエンドエンジニアが参照するドキュメントです。カラーパレット、タイポグラフィ、スペーシング、コンポーネントの使い方が定義されています。これをSKILL.mdとして定義すると、Claude Codeが「このプロジェクトのデザインルール」を理解した上でUIコードを生成できるようになります。

なぜこのアプローチが効果的なのか、3つの理由があります。

一貫性の自動担保について。人間が毎回デザインガイドを参照してコードを書く代わりに、スキルとして定義しておけばClaude Codeが常にガイドラインに沿ったコードを出力します。primary-blueの代わりに#1e88e5をハードコードしてしまうような事故がなくなります。

コンテキスト注入の効率化について。CLAUDE.mdにデザインシステム全体を書くと、関係ないタスクでもコンテキストを消費します。Skillsにしておけば、UI関連のタスクでのみ読み込まれるため効率的です。これはProgressive Disclosureの典型的な恩恵です。

段階的な拡張について。最初はカラーパレットだけ定義し、必要に応じてコンポーネント仕様、アニメーション仕様と段階的に拡張できます。CLAUDE.mdの肥大化を避けながら、デザインナレッジを蓄積できます。

具体的な実装例として、以下のような構成が考えられます。

.claude/skills/
  apply-design-system/SKILL.md      # UIコード生成時にデザインシステムを適用
  check-design-compliance/SKILL.md  # 既存コードのデザインガイドライン準拠チェック
.claude/agents/
  design-reviewer.md                # デザインレビュー専門のサブエージェント

筆者がmy-workプロジェクトに導入したSkills

参考までに、筆者（nogataka）が個人プロジェクトで運用しているSkillsの一部を紹介します。最初は「毎朝の工程表作成」が面倒だったため、daily-schedule スキルを作りました。Googleカレンダーから今日の予定を取得し、GitHub Issueの優先度と突き合わせ、その日のタスク順序を決めるという手順です。作った翌週には「トレンド調査」「記事下書き」「経理データ更新」と増えていき、今では20を超えるスキルが .claude/commands/ にコミットされています。重要なのは、最初から全部を作ろうとしなかった点です。困ったタイミングで1つずつ追加していく運用が最も長続きします。

自分のプロジェクトにSkillsを導入する実践手順

Step 1: 繰り返しパターンを洗い出す

まず、Claude Codeとの会話履歴を振り返り、繰り返し出している指示を特定します。「毎回PRレビューのたびに同じ観点を指示している」「デプロイ手順を毎回説明している」など、3回以上繰り返したパターンが候補です。

Step 2: 最初のSKILL.mdを作る

.claude/skills/<スキル名>/SKILL.md または .claude/commands/<名前>.md を作成し、最もよく使うワークフローを1つだけMarkdownファイルにします。必ずYAML frontmatterで name と description を定義してください。

mkdir -p .claude/skills/my-first-skill
touch .claude/skills/my-first-skill/SKILL.md

最初から完璧を目指す必要はありません。手順を箇条書きにするだけで十分機能します。

Step 3: 実際に使って磨く

呼び出して実際に使います。うまくいかない部分があれば手順を修正します。「この順番だとうまくいかない」「ここでユーザー確認が必要だった」といったフィードバックを反映して育てていきます。

Step 4: サブエージェント定義を分離する

スキルが複雑になり、複数の役割が含まれるようになったら、.claude/agents/ にサブエージェント定義を分離します。例えばリサーチスキルで「Web調査」「技術分析」「批判的レビュー」の3つの観点が必要なら、それぞれを別のエージェントファイルにします。

Step 5: CLAUDE.mdとの役割分担を整理する

Skillsが増えてきたら、CLAUDE.mdに書くべきことと、Skillsに書くべきことを整理します。判断基準はシンプルで、「常に適用されるべきルール」はCLAUDE.mdに、「特定タスクでのみ必要な手順」はSkillsに置きます。

Step 6: チームで共有しバージョン管理する

Skillsファイルはリポジトリにコミットできます。チームメンバーが同じスキルを使えるようにすることで、AIとの協業の品質がチーム全体で均質化します。運用のコツは、各スキルに「最終更新日」と「動作確認済みのClaudeバージョン」をfrontmatterに追記しておくことです。Claude Codeのアップデートで挙動が変わった際に、どのスキルを再検証すべきか即座に判断できます。

導入のロードマップ

段階的な導入の目安は次のとおりです。

最初の1週間: 最も頻度の高い1つのタスクをスキル化する。完璧さより「動くこと」を優先
最初の1ヶ月: 3〜5個のスキルに増やし、チームのレビューを受けてfrontmatterのdescriptionを磨き込む
最初の3ヶ月: CLAUDE.mdとの役割分担を見直し、重複を排除する。デザインシステムやコーディング規約など、ドメイン知識もSkills化する

Skills設計のアンチパターン5つ

1. 巨大なモノリシックスキル

1つのSKILL.mdに50ステップ以上の手順を詰め込むパターンです。コンテキストウィンドウを圧迫し、途中で手順を見失う原因になります。1スキル10〜15ステップ以内を目安にし、超える場合はサブエージェントに分割するか、前後半で別スキルにします。

2. 曖昧なトリガー条件

frontmatterの description に「コードを書くときに使う」のような曖昧な条件を書くと、関係ないタスクでも発火してしまいます。「Pull Requestのレビュー依頼を受けたとき」「デプロイを指示されたとき」のように、発火条件を具体化してください。逆に description が冗長すぎても discovery が劣化します。1〜2文で「何を」「いつ」を言い切るのが理想です。

3. 出力フォーマット未定義

手順だけ書いて出力フォーマットを定義しないと、毎回異なる形式で出力されます。テーブル、箇条書き、コードブロックなど、期待する出力形式を明示してください。ファイルに保存する場合はファイル名の命名規則も定義します。

4. 人間の判断ポイントの欠落

すべてを自動化しようとして、人間の承認が必要なポイントを見落とすパターンです。本番デプロイ、外部への公開、課金に関わる操作、外部顧客への送信など、取り消しが困難なアクションの前には必ずユーザー確認を挟む設計にします。

5. CLAUDE.mdとの重複

CLAUDE.mdに書いたルールをSkillsでも繰り返し書くと、片方を更新したときに矛盾が生じます。Skillsからは「CLAUDE.mdのルールに従って」と参照するだけにし、ルール本体はCLAUDE.mdに一元管理します。同様に、複数のSkills間で共通する手順は共通スキルに切り出して参照させるのが健全です。

まとめ

SKILL.mdによるワークフロー定義は、Claude Codeの活用を「プロンプトの工夫」から「業務プロセスの設計」に引き上げる仕組みです。superpowersの7フェーズワークフローが公開半年で約15万Starを獲得したのは、この考え方が多くの開発者に受け入れられた証拠であり、Anthropic自身が公式マーケットプレイスに採用したことで「Skills中心の拡張」が業界標準になりつつあることを示しています。

導入のコツは、最初から完璧なスキルを設計しようとせず、繰り返しているパターンを1つずつMarkdownに書き出すことから始めることです。Progressive Disclosure の恩恵を受けるには、1スキルを小さく、トリガーを明確に、出力を固定することが要です。使いながら磨いていけば、自分のプロジェクトに最適化されたスキルセットが自然にできあがります。

参考リンク

superpowers - GitHub (obra/superpowers) -- 約15万Star（148,000超）のClaude Code向けSkillsフレームワーク
Extend Claude with skills - Claude Code公式ドキュメント -- Skillsの公式仕様
Equipping agents for the real world with Agent Skills - Anthropic Engineering -- Skillsの設計思想（Progressive Disclosure）
Skill authoring best practices - Claude API Docs -- frontmatter設計のベストプラクティス
Claude CodeのCustom Slash Commandsでデザインシステムを丸ごとAIに教え込む - Zenn -- デザインシステムのSkills化事例
Claude Code Best Practices - Anthropic -- Anthropic公式のベストプラクティス

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up