【Claude Code】Skillsの設計思想と自作ガイド - 開発ワークフローを再利用可能にする

「Claude Code、便利だけど...毎回同じ指示を打つのが面倒なんだよな」

Issue分析して、コード書いて、テスト通して、コミットメッセージ考えて、PR作成して...。 「この一連の流れ、もう何十回やったかわからない」。

同じ指示を何度も打ち込んで、気づけば日が暮れている...そんな経験、ありませんか？

私たちも同じでした。そこで活用したのが、Claude CodeのSkills機能です。

この記事で学べること

• Claude Code Skillsの設計思想
• スキルの構造と自作方法
• 開発ワークフロー自動化のパターン

Claude Code Skillsとは

Claude Codeの機能を拡張する再利用可能なプロンプトとスクリプトの集合体です。

Skills機能を使うと、以下のことが可能になります：

1. よく使う指示をテンプレート化する
2. スラッシュコマンドで呼び出せるようにする
3. スクリプトで前処理・後処理を自動化する

私たちはこの機能を活用して、独自のスキル群を設計しました。

設計思想：3つの原則

1. 再利用性（Reusability）

同じ作業を二度書かない。一度定義したスキルは、単体でも、組み合わせても使い回せる。

例えば git-commit は単体で /git-commit として使えますが、dev-kickoff の一部としても呼び出されます。粒度を問わず再利用可能なのがポイントです。

~/.claude/skills/ に配置すれば、Claude Codeが自動認識。プロジェクト固有のスキルは .claude/skills/ に配置できます。

2. 構成可能性（Composability）

小さなスキルを組み合わせて、大きなワークフローを構築する。

dev-flow は dev-kickoff と pr-iterate という2つのオーケストレーターを呼び出します。dev-kickoff は更に6つの小さなスキルを順番に実行し、pr-iterate はレビューがLGTMになるまでループします（後述）。

3. 宣言的定義（Declarative）

「何をするか」を宣言し、「どうやるか」はClaude Codeに任せる。

# dev-flow/SKILL.md

## Workflow

1. `Skill: dev-kickoff` で開発フェーズを実行
2. `Skill: pr-iterate` でLGTM取得まで改善ループ

dev-flowのSKILL.mdはたったこれだけ。「dev-kickoffを呼んで、その後pr-iterateを回す」という意図だけを宣言しています。細かいことはClaudeが考えてくれます（人間は見守るだけ）。

スキルの構造

各スキルは統一された構造を持っています（一度覚えれば全スキル共通）：

skill-name/
├── SKILL.md         # スキル定義（必須）
├── scripts/         # 実行スクリプト
├── references/      # 参照ドキュメント
└── assets/          # アセット

SKILL.md：スキルの心臓部

---
name: git-commit
description: |
  Intelligent git commit with automatic change analysis.
  Use when: committing changes, creating commit messages.
user-invocable: true
---

# Git Commit

## Usage

`/git-commit [--all] [--amend]`

## Workflow

1. Run `scripts/analyze-changes.sh` to get staged changes
2. Analyze changes and determine commit type (feat/fix/refactor等)
3. Generate Conventional Commits format message
4. Execute commit

## References

- `references/conventional-commits.md` - コミットメッセージの規約

scripts/：自動化の要

Bash/Pythonスクリプトで、前処理・後処理を自動化します（手作業は機械に任せる主義）：

#!/bin/bash
# scripts/analyze-changes.sh

# ステージングされた変更を取得
git diff --cached --stat

# 変更ファイル一覧をJSON形式で出力
git diff --cached --name-only | jq -R . | jq -s .

スクリプトの出力をClaudeが解釈し、次のアクションを判断します。

references/：知識の蓄積

スキル固有の知識やテンプレートを配置：

references/
├── conventional-commits.md   # コミットメッセージ規約
├── review-checklist.md       # レビュー観点
└── templates/
    └── pr-description.md     # PRテンプレート

Claudeがこれらを参照しながら、一貫性のある出力を生成します（「あれ、前と違う形式だ」がなくなります）。

実践例：dev-flowスキル

私たちが最も重宝しているのが dev-flow スキルです。Issue番号を渡すだけで、PRのLGTM取得まで自動化します。

使い方

/dev-flow 123

これだけで以下が実行されます。手動でやると30分〜1時間かかる作業が、数分で完了します（まばたきしてる間に終わる勢い）。

dev-kickoff（開発フェーズ）:

1. 環境構築: 独立したWorktreeを作成
2. Issue分析: 要件・受け入れ条件を抽出
3. 実装: テストファーストで機能実装
4. 検証: テスト実行・品質チェック
5. コミット: 変更内容に応じたメッセージ生成
6. PR作成: Issue紐付け・説明文生成

pr-iterate（レビューループ）:

• レビュー対応: 指摘事項を修正してLGTMまで繰り返し

dev-flowの設計

dev-flowは2つのオーケストレーターを呼び出すメタスキルです：

# SKILL.md

## Workflow

1. `/dev-kickoff {issue}` で開発フェーズを実行
2. `/pr-iterate {pr}` でLGTM取得まで改善ループ

dev-kickoffが担当する6フェーズ：

pr-iterateが担当するレビューループ：

状態管理の工夫

長いワークフローでは「どこまで進んだか」を追跡する必要があります（3分前の自分が何をしていたか忘れるタイプにも優しい設計）：

// .claude/kickoff.json
{
  "issue": 123,
  "current_phase": "4_validate",
  "phases": {
    "1_prepare": { "status": "done" },
    "2_analyze": { "status": "done" },
    "3_implement": { "status": "done" },
    "4_validate": { "status": "in_progress" },
    "5_commit": { "status": "pending" },
    "6_pr": { "status": "pending" }
  }
}

これにより、途中で中断しても続きから再開できます（コーヒー休憩を挟んでも大丈夫）。

自作スキルの作り方

自分のチームに合ったスキルを作ってみましょう。

方法1: skill-creatorを使う（おすすめ）

実は、SKILL.mdやscriptsを手書きする必要はありません。skill-creatorを使えば、自然言語でお願いするだけでスキルが作れます。

# skill-creatorをインストール
/install skill-creator

# あとは自然言語でお願いするだけ
/skill-creator デプロイ前のチェックリストを実行するスキルを作って

これだけで、SKILL.md、scripts/、references/ を含む完全なスキルディレクトリが生成されます（手書きの苦労は何だったのか）。

skill-creatorが生成するもの：

対話形式で「どんなオプションが必要？」「エラー時はどうする？」と質問してくれるので、答えていくだけで完成します。

詳しくは Agent Skillsを一番かんたんに作る方法（Claude Code + skill-creator） が参考になります。

方法2: 手動で作る（構造を理解したい人向け）

skill-creatorを使わず、手動でスキルを作ることもできます。構造を理解したい場合はこちらがおすすめ。

Step 1: 繰り返し作業を特定する

「毎回同じことやってるな」と思う作業をリストアップ（デジャヴじゃないです、本当に同じことしてます）：

• PRレビューで同じ観点をチェックしてる
• デプロイ前に同じコマンドを打ってる
• ドキュメント更新時に同じフォーマットで書いてる

Step 2: SKILL.mdを書く

---
name: deploy-check
description: |
  Pre-deployment verification checklist.
  Use when: before deploying to production.
user-invocable: true
---

# Deploy Check

## Usage

`/deploy-check [--env staging|production]`

## Workflow

1. Run `scripts/check-env.sh` to verify environment
2. Check for uncommitted changes
3. Run test suite
4. Verify database migrations
5. Output deployment readiness report

## Checklist

- [ ] All tests passing
- [ ] No uncommitted changes
- [ ] Migrations applied
- [ ] Environment variables set
- [ ] Rollback plan documented

Step 3: スクリプトを追加（オプション）

複雑な前処理が必要なら、スクリプトを追加：

#!/bin/bash
# scripts/check-env.sh

ENV="${1:-staging}"

echo "Checking environment: $ENV"

# 環境変数チェック
if [[ -z "$DATABASE_URL" ]]; then
  echo "ERROR: DATABASE_URL not set"
  exit 1
fi

echo "Environment check passed"

Step 4: 配置して使う

# グローバルスキルとして配置
mkdir -p ~/.claude/skills/deploy-check
# SKILL.md, scripts/ を配置

# または、プロジェクト固有スキルとして
mkdir -p .claude/skills/deploy-check

あとは /deploy-check で呼び出すだけ。

設計のコツ

1. 小さく始める

最初から完璧を目指さない。まず動くものを作り、使いながら改善（深夜2時の完璧主義は翌朝の後悔のもと）。

## Workflow

1. Do the thing ← まずはこれだけでOK

2. 出力形式を統一する

スクリプトの出力はJSON形式で統一すると、Claudeが解釈しやすい：

echo '{"status": "success", "files_changed": 3}'

3. エラーハンドリングを明示する

「失敗したらどうするか」をWorkflowに書いておく：

## Error Handling

- If tests fail: Show failure details and suggest fixes
- If API returns error: Retry with exponential backoff

4. references/を活用する

チーム固有の規約やテンプレートは references/ に蓄積：

references/
├── coding-standards.md      # コーディング規約
├── review-checklist.md      # レビュー観点
└── error-messages.json      # エラーメッセージ定義

まとめ

Claude Code Skillsは、繰り返し作業を再利用可能なスキルとして体系化するアプローチです。

• 設計思想: 再利用性・構成可能性・宣言的定義
• 構造: SKILL.md + scripts/ + references/
• 実践: dev-flowのようなオーケストレーターで複数スキルを組み合わせ

「毎回同じ指示を打つのが面倒」という課題は、スキルとして切り出すことで解決できます。

まずは小さな繰り返し作業から始めてみてください。気づけば、あなたのチーム専用のスキルコレクションができているはずです（そして「なんであの頃手動でやってたんだろう」と思う日が来ます）。

→ お問い合わせはこちら