Claude Codeスキル自作の実際｜開発工程10本を覆うSKILL.md設計

Claude Code で同じ指示を何度も書いていると気づいたとき、その指示はスキルにできる。ただしスキル化すべきは手順そのものではない。1回きりの操作列ではなく、プロジェクトをまたいで繰り返し発生する判断——毎回迷う分岐や優先順位——をファイルに固定するのがスキルである。本稿は、筆者が開発工程全体を覆うように運用している自作スキル10本を実物に、その切り出しの基準と SKILL.md の書き方を整理する。

スキル化の基準

スキルにするかどうかの目安は単純である。2つ以上のプロジェクトで同じ指示を書いていたら、切り出す。1プロジェクト固有の決まりは後述の rules に置けばよく、横断して再利用する判断だけがスキルの対象になる。

もう一つの軸が、手順か判断かの区別である。「このコマンドを順に打つ」という操作の列は、書き下せば再現できるので、スキルよりコマンドやドキュメントが向く。スキルに載せる価値があるのは、毎回状況を見て決めている判断のほうだ。命名を短くするか説明的にするか、重複を今まとめるか3回目まで待つか、例外をその場で処理するか上位へ伝播させるか——こうした分岐は手順書に落ちない。答えが状況依存で、優先順位の形でしか書けないからである。

裏を返せば、判断の混ざらない純粋な操作列はスキルにしないほうがよい。起動しても判断材料が増えず、読み込みぶんだけ重くなる。スキル化の対象は、繰り返し現れて毎回迷う判断に絞る。

実例 — 開発工程を覆う10本構成

筆者の ~/.claude/skills/ には、開発の各工程に対応するスキルが10本ある。設計から文書化まで、作業のフェーズで守備範囲を切り分けているのが特徴だ。

設計      software-design（要件→設計・技術選定）／ agent-design（LLM を組むシステムの設計）
実装      coding-phase（実装フェーズの品質基準）
検証      testing-phase（テスト戦略）／ debugging（原因特定）／ review-phase（レビュー観点）
改善・運搬  refactoring（振る舞いを変えない改善）／ deployment（デプロイと CI/CD）
文書      tech-docs（README・API 仕様・手順書）
UI       web-design（UI/UX 判断）

10本を工程で分けているのは、守備範囲を重ねないためである。「実装して」で coding-phase、「テストを書いて」で testing-phase、「バグを直して」で debugging——起動条件をフェーズで区切ると、どの状況でどれが立ち上がるかが一意に決まる。守備範囲が重なると、同じ場面で複数が起動して判断が競合したり、逆にどれも起動しなかったりする。

各スキルの本体（SKILL.md）は40〜80行と薄い（2026-07-16 の実測で42〜78行）。本体にはワークフローと判断軸だけを置き、詳細は references/ に分ける。coding-phase なら pre-implementation・quality-standards・commit-granularity の3本、debugging なら triage・hypothesis・non-reproducible・post-fix の4本、というように、本体から必要なときだけ開く下位ファイルを持つ。references はスキルによっておおむね2〜6本ある。

工程で覆うと、設計から運搬・文書化までの判断が同じ粒度でそろい、プロジェクトが変わっても同じ基準で作業できる。

SKILL.md はトリガー記述が命

スキルは、SKILL.md 冒頭の frontmatter にある description をトリガーとして起動する（仕組みは 2026-07-16 時点、Claude Code v2.1.211 で確認）。この description の書き方が、スキルが効くかどうかを決める。

筆者の10本には共通の型がある。起動させたい言い回しを動詞で列挙し、最後に「明示的な依頼がなくても必ず参照する」で締める。実物として coding-phase の description を挙げる。

実装フェーズの品質基準を一貫させるスキル。「実装して」「コードを書いて」「機能を追加して」「バグを修正して」「リファクタリングして」「コミットして」等、コードを書く・変更する作業全般で起動する。新規実装、既存コードベースへの変更、コミット分割・メッセージ作成を含め、設計確定後の実装作業では明示的な依頼がなくても必ず参照する。

前半で「実装して」「コミットして」といった実際の依頼文に近い動詞句を並べ、後半で適用範囲を言い切る。この形にする理由は二つある。トリガーが曖昧だと、起動してほしい場面で立ち上がらない。逆に広すぎると、無関係な作業でも誤って起動して判断を濁す。実際に自分が打つ言い回しを列挙し、範囲を絞って書くのが、この綱引きの解になる。

揮発情報と詳細の隔離

SKILL.md 本体を薄く保つのは、読み込みを軽くするためである。トリガーが当たると本体が読まれる。ここが厚いと、起動のたびに重くなる。だから本体には変わりにくい判断軸だけを残し、詳細・テンプレート・変化の速い情報は references/ へ逃がす。

deployment スキルがその例だ。本体はツール非依存の原則（パイプラインのステージ設計、デプロイ前確認、ロールバック）に徹し、GitHub Actions の具体は github-actions.md として references に隔離している。ツールが変わっても本体の判断軸は生き残り、差し替えるのは実装例のファイルだけで済む。揮発しやすい情報を本体から締め出すこの分離は、確認日で鮮度を管理する運用（別記事で扱う）とも噛み合う。

薄い本体に判断軸、references に詳細——この構造は、CLAUDE.md を薄く保ち rules に分散させる設計（別記事）とまったく同型である。

よくある質問

スキルと rules の違い。 rules はリポジトリ固有の契約で、プロジェクトに従属する。スキルは横断して使う判断基準で、ユーザーに従属する。だから置き場所も .claude/rules/ と ~/.claude/skills/ に分かれる。両方に同じことを書かず、1プロジェクト限定なら rules、横断利用ならスキルへ寄せる。devlog を記事化するといった特定プロジェクト固有のワークフロー用スキルだけは、例外的にそのリポジトリの .claude/skills/ に同梱する。

起動しないとき。 description の起動フレーズを見直す。自分が実際に打った言い回しが、列挙した動詞句に含まれているかを確かめ、無ければ足す。

まとめ

スキル化すべきは手順ではなく、プロジェクトをまたいで繰り返す判断である。2つ以上で同じ指示を書いたら切り出し、SKILL.md 本体には判断軸だけを薄く置き、詳細と揮発情報は references に逃がす。起動はすべて description のトリガー記述にかかる——実際に打つ言い回しを動詞で並べ、範囲を絞って書く。開発の全工程をこの粒度でそろえておくと、プロジェクトが変わっても同じ基準で手を動かせる。