Claude Code の Skill・Issue・CLAUDE.md の使い分けを整理した

Claude Code を使い始めてしばらく経ち、Issue ベースで作業を指示するフローは固まってきた。そこで気になっていた Skill という仕組みを調べた。「繰り返し依頼に便利」とは聞いていたが、実際に何をするもので、Issue や CLAUDE.md と何が違うのかを整理しておきたかった。

Skill とは何か

Skill は .claude/skills/<skill-name>/SKILL.md の形で置く Markdown ベースの追加手順だ。ファイルには YAML front matter の description と、実行時の指示を書く。

呼び出され方は2通りある。

• Claude Code が description を見て関連すると判断したとき、自動で読み込む
• ユーザーが /skill-name の形で明示的に呼び出す

Skill ディレクトリにはテンプレートや参考資料、スクリプトも同梱できる。プロジェクト単位・個人環境単位のどちらにも置ける。

公式ドキュメントでは、同じ指示やチェックリストを何度もチャットに貼っている場合や、CLAUDE.md の一部が事実ではなく手順書になってきた場合に Skill 化するとされている。本文は使われるときだけ読み込まれるため、長い参照資料を常時コンテキストに入れずに済む点がメリットだ。

Commands との関係

以前は .claude/commands/deploy.md という単一ファイル方式のカスタムコマンドがあった。現在は Skills に統合されており、どちらも /deploy のようなスラッシュコマンドとして動く。

既存の .claude/commands/ は引き続き動作するが、新しく作るなら .claude/skills/ が推奨だ。

Skill の書き方

SKILL.md の構造

SKILL.md は2つのパートで構成される。

---
name: gen-test
description: テストを生成する
disable-model-invocation: true
---

以下のファイルのテストを生成する: $ARGUMENTS

1. ソースファイルを読む
2. テスト対象の関数を特定する
3. プロジェクトの規約に沿ったテストを書く

--- で囲まれた上部が frontmatter で、Claude に「この Skill をいつ・どう使うか」を伝える設定欄だ。YAML 形式で書く。--- 以降が実際の指示内容になる。

frontmatter の主な項目は次のとおり。

引数を受け取る（$ARGUMENTS）

/skill-name 対象ファイル のようにスラッシュコマンドに引数を渡すと、SKILL.md 内の $ARGUMENTS に展開される。

---
name: fix-issue
description: GitHub の Issue を修正する
disable-model-invocation: true
---

GitHub Issue $ARGUMENTS を修正する。

1. Issue の内容を読む
2. 修正を実装する
3. テストを書く
4. コミットする

/fix-issue 123 と呼ぶと、$ARGUMENTS が 123 に置き換わって Claude に渡る。$ARGUMENTS を書かない場合は末尾に ARGUMENTS: 123 が自動で追記される。

実行時にコマンド結果を埋め込む

!`コマンド` の形で書くと、Skill が呼び出されたタイミングでコマンドを実行し、その結果をプロンプトに差し込んでから Claude に渡す。

---
name: release-notes
description: 直近のコミットからリリースノートを生成する
disable-model-invocation: true
---

## 直近の変更
- 前回タグ以降のコミット: !`git log $(git describe --tags --abbrev=0)..HEAD --oneline`
- 前回タグ: !`git describe --tags --abbrev=0`

上記をもとにリリースノートを作成する。

毎回手動でコミットログを貼らなくても、呼び出した瞬間の実際の状態が自動で入る。Claude はコマンドの結果だけを受け取り、コマンド自体は見えない。

Issue と何が違うか

混同しやすいのが Issue との使い分けだ。一言でいうと、Issue は「今回やってほしいこと」で、Skill は「毎回守ってほしい作業方法」だ。

Issue にすべて書く方式でも作業はできる。ただし毎回同じ注意事項を貼るほど、依頼文が長くなり、今回だけの重要事項が埋もれやすくなる。

分担としては、Issue には「今回の目的・対象・制約」を書き、Skill には「毎回共通の進め方」を置くのが扱いやすい。

CLAUDE.md との違い

CLAUDE.md は常に効いてほしいルールに向いている。

• main に直接コミットしない
• 特定のデプロイ環境を前提として扱う
• 記事編集時は確認 URL を提示する

こういった「常に守るべきルール」は CLAUDE.md に置くべきだ。Skill にだけ置くと、呼び出されなかったときにルールが抜ける可能性がある。

Skill は、常時読むほどではないが、特定の作業では詳しく読んでほしい手順に向く。

• 記事リライト時の候補選定・質問・履歴更新の流れ
• UI 変更時のビルド・プレビュー・スクリーンショット確認の流れ
• PR 前の差分確認・リスク整理の手順

Skill に向く作業・向かない作業

実際に作った例：pr-merge

最初に Skill 化したのは PR のマージ手順だ。.claude/skills/pr-merge/SKILL.md の中身はこうなっている。

---
name: pr-merge
description: PRをマージしてローカルに反映する。「マージして」「PRをマージ」と言われたときに使う。
disable-model-invocation: true
allowed-tools: Bash
---

PR番号: $ARGUMENTS

以下の手順を実行する。

## 1. PR情報を確認する

```
gh pr view $ARGUMENTS --repo your-org/your-repo --json number,title,baseRefName,state -q '"#\(.number) \(.title)\nbase: \(.baseRefName)\nstate: \(.state)"'
```

## 2. base ブランチを確認する

- base が `main` の場合: **必ずユーザーに確認を取る**。「PR #XXX は main へのマージです。実行してよいですか？」と聞き、承認を得てから次へ進む。
- base が `develop` またはその他の場合: そのまま次へ進む。

## 3. マージする

```
gh pr merge $ARGUMENTS --repo your-org/your-repo --merge
```

## 4. ローカルに反映する

base ブランチにチェックアウトして、fast-forward のみで pull する。マージコミットを作らないために `--ff-only` を使う。

```
git checkout <baseRefName>
git pull --ff-only
```

## 5. 完了を報告する

PR番号・タイトル・マージ先ブランチを1行で報告する。

/pr-merge 391 と呼ぶだけで、PR 確認・main チェック・マージ・ローカル反映まで一気に流れる。

最初は git pull だけ書いていた。実際に使うと余計なマージコミットがローカルに生まれた。--ff-only に直すことで fast-forward できないときは失敗して止まるようになった。こういう「動かして直す」サイクルが Skill では速い。

向かない作業

• 1回だけの依頼
• 今回だけの対象 URL・記事名・Issue 番号（それは Issue に書く）
• セキュリティ上の強制ルール（CLAUDE.md に置く）
• まだ固まっていない試行錯誤中の手順

導入の順序

いきなり Skill を大量に作るより、段階的に試す方が安全だ。

1. .claude/skills/ を増やす前に、Skill 化候補を docs/ で文書として整理する
2. 繰り返しが多く、手戻り削減効果が大きいものから 1 つだけ Skill 化する
3. Skill の description に「いつ使うか」を具体的に書く
4. 常時必要なルールは CLAUDE.md に残す
5. 1〜2 週間使って、勝手に呼ばれて困るか、呼ばれずに困るかを確認する

pr-merge を最初に作ったのは、手順が短く・引数が PR 番号だけで・頻度も高かったからだ。最初の Skill は小さいほどいい。

まとめ

Skill は「Issue の代わり」ではなく、「Issue に毎回書いていた共通手順を外に出す場所」だ。

• CLAUDE.md: 常に守るルール
• Issue: 今回の依頼
• Skill: 繰り返し作業の詳細手順

この分担で整理すると、Issue が短くなり、今回だけの指示が埋もれにくくなる。まずは小さく固定化された作業から Skill 化して、効果が見えたら広げていく。

参考

• Extend Claude with skills — Claude Code 公式ドキュメント
• Commands — Claude Code 公式ドキュメント