こんにちは、小林です!
株式会社リンクアンドモチベーションでデータアナリスト兼データスチュワードをしています。普段はデータ分析業務をやりつつ、データ基盤の品質管理も推進しています。最近は Claude Code を自分好みにカスタマイズして開発ワークフローを整備することにハマっていて、めちゃくちゃ楽しいです!
それでは記事に入ります。
はじめに
- 前回の記事で Claude Code の Skills の概要と tech-writing スキルを紹介した。今回はその作り方の話
- 65 個のスキル（6 グループ + 21 スタンドアロン）を作る中で、スキル作成自体に型が必要だと気づいた
- 設計原則・構造パターン・作成プロセスを 1,411 行の「スキルを作るスキル」 に体系化した
- 「スキルは太らせるな」「危ない操作ほどガチガチに」「要るときに要る分だけ」の 3 原則が核
20 個乱立から始まった
最初の 5-6 個は勢いで作れた。think、bigquery-prod、slack-cli。用途が明確で、構造も単純だった。
象徴的なのが think。今はグループスキルとして think/reference/ 配下に 7 つの子スキルがぶら下がっているが、当時は classify、matrix、criteria... が全部 ~/.claude/skills/ 直下にバラバラに置かれていた。「思考道具」という親概念でまとめる発想がなかった。
問題は 10 個を超えたあたりから始まった:
- 構造がバラバラ — あるスキルは全部 SKILL.md に詰め込み、別のスキルは scripts/ に分離。一貫性がない
- SKILL.md が肥大化 — 1,000 行超えの SKILL.md を作ってしまい、コンテキストウィンドウを圧迫
- グループ化の判断基準がない — 3 つ以上の関連スキルをまとめるべきか、スタンドアロンのままにすべきか
- 新しいスキルを作るたびに車輪の再発明 — ディレクトリ構造を毎回手作業で作り、フロントマターのフォーマットを思い出す
転機: Slack で流れてきた一言
ある日、社内の Slack でこんなメッセージが流れてきた。
claudeのスキル(skill/command)を作るときは徒手空拳でやるより skill-creator を通したほうが絶対に良いです。claude はスキルを作るのが抜群に上手いです。再現性を持たせたい作業や、そもそも作業手順の抽象化・言語化を行いたい時は積極的にスキルを作ることを検討してください。
添えられていたのが Anthropic公式「skill-creator」完全ガイド という Zenn 記事。skill-creator の導入から活用まで体系的にまとめられていた。
「めっちゃありがたい！」と反応して、その日のうちに skill-creator を導入した。そこから何が変わったか:
- スキル作成のガイドラインを定義した
- 既存 20 スキルを修正して構造を統一した
- スキルの従属関係を意識した設計（グループスキル、依存チェーン）に切り替えた
結果として 65 スキルまで成長した。「型がないと破綻する」は実際に破綻しかけた経験から来ている。
設計原則 — 3 つの柱
65 スキルを作る中で固まった、スキル設計の 3 原則。
1. Concise is Key — スキルは太らせるな
これが最も重要な原則。
Claude Code の Skills は コンテキストウィンドウを他の全てと共有する。システムプロンプト、会話履歴、他のスキルのメタデータ、ユーザーのリクエスト。スキルが太れば太るほど、他に使える容量が減る。
前提: Claude は既に非常に賢い。 Claude がまだ持っていない情報のみ追加する。「Claude にこの説明は本当に必要か？」「この段落はトークンコストに見合うか？」と各情報を吟味する。
ここがミソなんだけど、冗長な説明よりも簡潔な例を優先する。「JSON フォーマットで出力してください。JSON とは...」みたいな説明は不要。Claude は JSON を知っている。必要なのは「このスキーマで出力しろ」という具体例だけ。
実際、65 スキルを作る過程で SKILL.md が 500 行を超えたものが何個かあった。そのたびに references/ や scripts/ に分離して SKILL.md を軽量化した。data-governance の子スキル quality-rules は SKILL.md だけで 553 行あるが、これは品質ルールの定義テーブルが大量に必要なので仕方ない。「仕方ない」と言い切れるかどうかが判断基準。
2. Degrees of Freedom — 危ない操作ほどガチガチに
スキルの指示をどこまで具体的に書くか。この判断基準が「自由度」。
Claude が道を探索していると考える。崖のある狭い橋にはガードレール（低自由度）が必要で、開けた野原では多くのルート（高自由度）が許される。
| 自由度 | 使い方 | 実装手段 | 実例 |
|---|---|---|---|
| 高 | 複数アプローチが有効、コンテキスト依存 | テキストベースの指示 | tech-writing の Human Heat フェーズ |
| 中 | 推奨パターンあり、設定で動作が変わる | 疑似コードまたはパラメータ付きスクリプト | data-governance のルーティングロジック |
| 低 | 操作が脆弱、一貫性が重要、手順厳守 | 具体的なスクリプト | bigquery-prod の SQL 実行スクリプト |
たとえば bigquery-prod の execute_sql.js は低自由度。SQL インジェクションを防ぎ、SELECT のみ許可し、dry_run オプションを提供する。Claude に「いい感じに SQL を実行して」と任せたら本番データを壊すリスクがある。橋にはガードレールが要る。
一方、tech-writing の「AI 臭を消す」フェーズは高自由度。「まとめると」を自分の言葉に置き換える、口語的なリズムを入れる。具体的な置換ルールをスクリプトにしても意味がない。野原では自由に走ればいい。
3. Progressive Disclosure — 要るときに要る分だけ
スキルは 3 段階で読み込まれる。全部を一度に読み込まない。
Level 1: メタデータ（name + description） → 常にコンテキスト内（~100 語）
Level 2: SKILL.md 本文 → スキル発動時に読み込み（< 5,000 語）
Level 3: バンドルリソース（scripts/references/） → 必要に応じて読み込み（実質無制限）
ここで重要なのは Level 1 の description が唯一のトリガー だということ。Claude は全スキルの description を常に見ている。ユーザーの発言がどのスキルに該当するかを description で判断し、該当するスキルの SKILL.md 本文（Level 2）を読み込む。
つまり description の書き方でスキルの発動精度が決まる。
# Bad: 何のスキルか不明
---
name: my-skill
description: "便利なスキル"
---
# Good: いつ使うかが明確
---
name: bigquery-prod
description: "BigQuery本番環境のツール（読み取り専用）。bqコマンドを使用して
BigQueryにアクセスします。サーベイ結果の平均値クエリにも対応。「サーベイ平均」
「満足度の平均」等のリクエストで survey_averages スクリプトを使用。"
---
スキルの作り方 — 構造と 6 ステップ
原則を押さえたら、次は具体的な作り方。
スキルの構造
全てのスキルは以下で構成される:
skill-name/
├── SKILL.md (必須: YAML フロントマター + Markdown 本文)
├── scripts/ → 実行可能コード（トークン消費ゼロ。読まずに実行できる）
├── references/ → 参照ドキュメント（必要時のみ読み込み）
└── reference/ → 子スキル（グループスキルの場合のみ）
├── child-a/
│ └── SKILL.md
└── child-b/
└── SKILL.md
Progressive Disclosure で述べた通り、scripts/ は Level 3 のリソース。注目すべきは「同じコードを毎回生成させなくて済む」点で、動作が確定的になるし、Claude のコード生成分のトークンも節約できる。
スキルは AI エージェントが仕事をするための情報だけ を含む。README.md、CHANGELOG.md、セットアップ手順、ユーザー向けドキュメントは不要。ここを間違えると、スキルがドキュメント置き場になって肥大化する。
6 ステップの作成プロセス
1. Understand → 2. Plan → 3. Initialize → 4. Edit → 5. Package → 6. Iterate
Step 1: 具体例でスキルを理解する
いきなり SKILL.md を書き始めない。まず「このスキルがどう使われるか」の具体例を集める。
- 「このスキルをどの場面で使う？」
- 「ユーザーがどう言ったら発動すべき？」
- 「既存のどのスキルと組み合わせる？」
data-governance を作るとき、最初に 50+ の本番 BigQuery データセットをスキャンして、実際のアンチパターン（tbl_data01、flag1 カラム等）を収集した。この具体例があったから naming スキルの Anti-Pattern テーブルが作れた。
Step 2: 再利用可能なコンテンツを計画する
具体例をもとに、scripts/ と references/ に何を入れるか決める。
- 同じコードを毎回書き直してる？ →
scripts/に入れる - Claude が作業中に参照すべき情報がある？ →
references/に入れる
Step 3: 初期化（init_skill.py）
# スタンドアロン
scripts/init_skill.py my-skill --path ~/.claude/skills
# グループスキル
scripts/init_skill.py data-governance --path ~/.claude/skills \
--group --children naming,modeling,dictionary,quality-rules,lineage
テンプレートが生成される。フロントマター、ディレクトリ構造、サンプルファイル。手作業でやると必ずどこかミスるので、スクリプト化した。
Step 4: 編集
生成されたテンプレートを実際の内容に書き換える。ここが一番時間がかかる。
ポイント:
- description が全て（Progressive Disclosure で書いた通り）。本文にしか書いてない情報はスキル発動前に参照されない
- SKILL.md は 500 行以下を目指す。超えたら references/ に分離
- スクリプトは実際に動かしてテスト。動かないスクリプトは信用を破壊する
Step 5: パッケージ化（package_skill.py）
scripts/package_skill.py ~/.claude/skills/my-skill
検証 → パッケージ化を自動でやる。フロントマターの形式、必須フィールド、ディレクトリ構造をチェックして、問題なければ .skill ファイル（zip 形式）を生成。
Step 6: イテレーション
スキルは作って終わりじゃない。使ってみて初めてわかることがある。
実際、tech-writing は最初 200 行だった。9 本の参考記事を読み込ませて 370 行に成長した。data-governance の naming は最初コンパクトだったが、本番データセットのスキャン結果を反映して 281 行に膨らんだ。
使う → 足りない部分に気づく → SKILL.md を更新 → また使う。このサイクルを回すことでスキルが育つ。
スケールさせる — 乱立を整理する
スキルが 10 個を超えたら、この章の出番。
グループスキルパターン — 親ルーター + 子スキル
関連する複数のスキルをグループ化するかどうか。65 スキルの中で最も設計判断が求められた部分。
| 判断基準 | スタンドアロン | グループ |
|---|---|---|
| サブドメインが親概念を共有する | No | Yes |
| 別のエージェントが独立して使う | Yes | No |
| 関連スキルの数 | 1-2 | 3+ |
| ワークフローチェーンを形成する | No | Yes |
2 つの関連スキルをグループ化しても、親ルーターのオーバーヘッドに見合わない。3 つ以上になったらグループ化を検討する。子が多いほどルーターの価値が上がる。
親 SKILL.md はルーターとして機能する。中身は:
- Overview — グループが何をカバーするか（1-2 文）
- Child skill table — 各子の名前・目的・トリガー条件
- Selection Logic — どの子スキルを選ぶかの判断フロー
- Workflow — 子スキル間の関係（該当する場合）
development-deck（10 子スキル）の親ルーターを例に取ると:
メインフローは左から右に流れるが、フェーズをスキップするショートカットがある。spec-ops はどのフェーズからも呼べる横断スキル。idea-breaker は設計が煮詰まったときだけ発動する。
こういう分岐と合流がある複雑なフローこそ、親ルーターに Selection Logic を書く価値がある。data-governance のような直列チェーンなら SKILL.md に依存順を書くだけで済むが、development-deck レベルになるとルーターなしでは Claude が正しいスキルを選べない。
命名規約: reference/ と references/ は別物
ここは声を大にして言いたい。
| ディレクトリ | 目的 | 中身 |
|---|---|---|
reference/（単数形） |
子スキルのディレクトリ | 各子の SKILL.md
|
references/（複数形） |
参照ドキュメント | Markdown ファイル |
data-governance/
├── SKILL.md
└── reference/ # ← 単数形: 子スキルが入る
├── naming/
│ └── SKILL.md
└── modeling/
└── SKILL.md
skill-creator/
├── SKILL.md
└── references/ # ← 複数形: 参照ドキュメントが入る
├── design-patterns.md
└── workflows.md
混在させると Claude が「このディレクトリの中身はスキルなのか？参照ドキュメントなのか？」と混乱する。
整理した結果
20 個の乱立を整理し、新しいスキルを型に沿って追加し続けた結果がこれ:
~/.claude/skills/
├── skill-creator/ # ← 今回の主役。スキルを作るスキル
│ ├── SKILL.md # 572 行の作成ガイド
│ ├── scripts/
│ │ ├── init_skill.py # スキル初期化
│ │ ├── package_skill.py # パッケージ化
│ │ └── quick_validate.py # 検証
│ └── references/
│ ├── design-patterns.md # 設計パターン集
│ ├── workflows.md # ワークフローパターン
│ └── output-patterns.md # 出力パターン
├── SKILL-MAP.md # 全 65 スキルの索引
├── think/ # 7 子スキル
├── data-governance/ # 5 子スキル
├── doc-processor/ # 5 子スキル
├── design-studio/ # 6 子スキル
├── development-deck/ # 10 子スキル
├── startproject/ # 5 子スキル
├── tech-writing/ # スタンドアロン
├── bigquery-prod/ # スタンドアロン
└── ... (他 19 スタンドアロン)
| グループ | 子スキル数 | パターン |
|---|---|---|
| think | 7 | 選択型（思考道具 7 つから 1 つ選ぶ） |
| doc-processor | 5 | ファイル形式ルーティング（.pdf → pdf, .docx → docx） |
| design-studio | 6 | タスク種別ルーティング |
| startproject | 5 | 順次ワークフロー（理解 → 実装 → レビュー） |
| data-governance | 5 | 依存チェーン（naming → modeling → dictionary → quality-rules → lineage） |
| development-deck | 10 | フロー + 任意呼び出しの混合 |
65 スキル。グループ 6 つ（親 6 + 子 38 = 44）、スタンドアロン 21。
65 スキルから見えた実践知見
SKILL-MAP.md は必須。 65 スキルになると、自分でも全体像を把握できなくなる。全スキルのインデックスを管理して、新しいスキルを作ったら必ず更新する。これがないと「あのスキル、もう作ったっけ？」が発生する。
scripts/ はケチらない。 同じコードを 2 回以上 Claude に生成させたら、scripts/ に入れるべき。トークン消費がゼロになるし、動作が確定的になる。bigquery-prod は 7 本のスクリプトを持っていて、SQL 実行からテーブル情報取得まで全部スクリプト化している。
参考記事
| 記事 | 抽出した知見 |
|---|---|
| Anthropic公式「skill-creator」完全ガイド（Zenn） | skill-creator の導入から活用まで。導入のきっかけになった記事 |
| anthropics/skills（GitHub） | Anthropic 公式のスキル実装例。構造パターンの参考にした |
| yamato-snow/skills（GitHub） | 上記の日本語フォーク。日本語でのスキル記述例として参照 |
まとめ
- skill-creator は「スキルの作り方」のスキル — メタだけど、65 個作るには型が必要だった
- 3 原則が核 — スキルは太らせるな（簡潔に）、危ない操作ほどガチガチに（自由度を合わせる）、要るときに要る分だけ（Progressive Disclosure）
-
グループスキルパターンが最も設計判断を要する —
reference/（単数形）とreferences/（複数形）の区別を間違えるな - 使って育てる — スキルは作って終わりじゃない。使う → 気づく → 更新のサイクルを回す
次回はこの skill-creator を使って実際に作った data-governance スキル 5 本（命名 → モデリング → 辞書 → 品質 → リネージ）の中身を紹介する。
付録: skill-creator の SKILL.md 全文
実際に使用している skill-creator の SKILL.md をそのまま掲載する。記事本文で紹介した原則・構造・プロセスが、スキル定義としてどう記述されているかの参考にしてほしい。
572 行ある。本文中で「SKILL.md は 500 行以下を目指す」と書いておきながら自分のが超えているのは自覚している。ただ、skill-creator は「スキルの作り方」という全スキル共通の横断的知識を扱うため、原則・構造・6ステップのプロセス・グループスキルパターンまで含めるとこの量になる。data-governance の quality-rules（553 行）と同じで、「削ったら機能しない」なら仕方ない。
なお、フロントマター（name, description）は Claude がスキル発動判定に使う部分なので英語のまま。本文も Claude が読む前提で英語で書いている。
skill-creator/SKILL.md を展開する
---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---
# Skill Creator
This skill provides guidance for creating effective skills.
## About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.
### What Skills Provide
1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
## Core Principles
### Concise is Key
The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
### Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability:
**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
### Anatomy of a Skill
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ ├── description: (required)
│ │ └── compatibility: (optional, rarely needed)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
#### SKILL.md (required)
Every SKILL.md consists of:
- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used.
- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
#### Bundled Resources (optional)
##### Scripts (`scripts/`)
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
##### References (`references/`)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- **When to include**: For documentation that Claude should reference while working
- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window.
##### Assets (`assets/`)
Files not intended to be loaded into context, but rather used within the output Claude produces.
- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
#### What to Not Include in a Skill
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc.
### Group Skills (Parent Router + Child Skills)
When a skill covers multiple related sub-domains that share a parent concept, use the **Group Skill** pattern instead of creating multiple standalone skills. The parent SKILL.md acts as a router, and each child skill lives in its own subdirectory under `reference/`.
#### Structure
group-skill-name/
├── SKILL.md # Parent router: selection logic + overview
└── reference/ # Child skills (singular "reference", NOT "references")
├── child-a/
│ └── SKILL.md # Child skill with its own frontmatter + body
├── child-b/
│ └── SKILL.md
└── child-c/
├── SKILL.md
└── references/ # Child can have its own reference docs
└── api_reference.md
**CRITICAL: Directory naming convention:**
| Directory | Purpose | Example |
|-----------|---------|---------|
| `reference/` (singular) | Contains **child skill directories**, each with its own SKILL.md | `think/reference/classify/SKILL.md` |
| `references/` (plural) | Contains **reference documents** (markdown files, not skills) | `skill-creator/references/design-patterns.md` |
These are NOT interchangeable. Mixing them breaks the convention and confuses Claude about whether a subdirectory is a child skill or a reference document.
#### When to Use Group vs Standalone
| Criterion | Standalone | Group |
|-----------|-----------|-------|
| Sub-domains share a parent concept | No | **Yes** |
| Skills are used independently by different agents | **Yes** | No |
| Number of related skills | 1-2 | **3+** |
| Skills form a workflow chain | No | **Yes** |
**Examples of existing group skills:**
- `think/` (7 children): classify, matrix, criteria, structure, isolate, systems, reflection
- `doc-processor/` (5 children): pdf, docx, pptx, xlsx, coauthoring
- `design-studio/` (6 children): frontend, uiux, canvas, generative, artifacts, tracker
- `development-deck/` (10 children): development-partner, design-partner, spec-writer, etc.
- `startproject/` (4 children): team-implement, team-review, gemini-system, checkpointing
#### Parent SKILL.md Structure
The parent acts as a router. Its body contains:
1. **Overview** - What the group covers (1-2 sentences)
2. **Child skill table** - Name, purpose, and trigger conditions for each child
3. **Selection logic** - How to choose the right child skill
4. **Workflow** (if applicable) - How children relate to each other
#### Child SKILL.md Structure
Each child is a full skill with its own frontmatter, but scoped to its sub-domain.
#### SKILL-MAP.md Update Requirement
**After creating any new skill (standalone or group), update `~/.claude/skills/SKILL-MAP.md`:**
- For **group skills**: Add a new entry under "## Group Skills" with the directory tree showing parent and children
- For **standalone skills**: Add a new row to the "## Standalone Skills" table
- Update the **skill counts** at the bottom of the file
This is a mandatory step. SKILL-MAP.md is the authoritative index of all skills and must stay in sync.
#### Initializing a Group Skill
Use `init_skill.py` with the `--group` flag:
scripts/init_skill.py group-name --path ~/.claude/skills --group --children child-a,child-b,child-c
This creates the parent SKILL.md as a router template and each child's SKILL.md under `reference/<child>/`.
### Progressive Disclosure Design Principle
Skills use a three-level loading system to manage context efficiently:
1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
#### Progressive Disclosure Patterns
Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
For concrete examples of these patterns, see references/design-patterns.md.
**Important guidelines:**
- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
## Skill Creation Process
Skill creation involves these steps:
1. Understand the skill with concrete examples
2. Plan reusable skill contents (scripts, references, assets)
3. Initialize the skill (run init_skill.py)
4. Edit the skill (implement resources and write SKILL.md)
5. Package the skill (run package_skill.py)
6. Iterate based on real usage
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
### Step 1: Understanding the Skill with Concrete Examples
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What would a user say that should trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
### Step 2: Planning the Reusable Skill Contents
To turn concrete examples into an effective skill, analyze each example by:
1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
1. Rotating a PDF requires re-writing the same code each time
2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
### Step 3: Initializing the Skill
At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
Usage:
scripts/init_skill.py <skill-name> --path <output-directory>
The script:
- Creates the skill directory at the specified path
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
- Creates example resource directories: `scripts/`, `references/`, and `assets/`
- Adds example files in each directory that can be customized or deleted
After initialization, customize or remove the generated SKILL.md and example files as needed.
### Step 4: Edit the Skill
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
#### Learn Proven Design Patterns
Consult these helpful guides based on your skill's needs:
- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
These files contain established best practices for effective skill design.
#### Start with Reusable Skill Contents
To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input.
Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected.
Any example files and directories not needed for the skill should be deleted.
#### Update SKILL.md
**Writing Guidelines:** Always use imperative/infinitive form.
##### Frontmatter
Write the YAML frontmatter with `name` and `description`:
- `name`: The skill name
- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
- Include both what the Skill does and specific triggers/contexts for when to use it.
- Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
Do not include any other fields in YAML frontmatter.
##### Body
Write instructions for using the skill and its bundled resources.
### Step 5: Packaging a Skill
Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
scripts/package_skill.py <path/to/skill-folder>
Optional output directory specification:
scripts/package_skill.py <path/to/skill-folder> ./dist
The packaging script will:
1. **Validate** the skill automatically, checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Description completeness and quality
- File organization and resource references
2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
### Step 6: Iterate
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
**Iteration workflow:**
1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again