Claude Code の skill 機能を本格的に試す - 開発フローを丸ごと任せて PR まで完結させた話

はじめに

開発の現場において、AIエージェントはもう手放せなくなっていますよね。
私も日々お世話になっているのですが、あまりうまく活用できていない気がしていました。

Claude Code を普段から使用しており、skill 機能を使ってみよう思っていたものの、なかなか試せず時間が経ち...
そんなある日 2026 年 4 月中旬に GitHub CLI で gh skill サブコマンドが追加され、Anthropic 公式の skill 群を 1 コマンドで導入できるようになったと聞きました。

ちょうどリファクタリングしようかなと思っていた自分のブログサイト (atsushi11o7/fumiblog) があったので、ここに Claude Code の skill 機能を導入して作業しようと思い立ちました。

そこで、

1. Dev Container で Claude Code 前提の開発環境を整える
2. gh skill で公式 skill を導入する
3. 自作 skill で開発ワークフローを定義する
4. 話題になっていたfrontend-design skill に従って適当なコンポーネントを再設計する
5. PR 提出までを Claude Code 上で完結させる

という流れを通しでやってみました。本記事はその記録です。

1. 環境構築: Dev Container + MCP + GitHub CLI

Claude Code を中心に据えた開発環境を、Dev Container（Dockerfile + devcontainer.json）と MCP 設定（.mcp.json）の 3 ファイルで組み立てていきます。

Dockerfile

ベースは node:24-trixie-slim で、追加するのは GitHub CLI と Claude Code 本体の 2 つだけというシンプル構成です。

FROM node:24-trixie-slim

ENV DEBIAN_FRONTEND=noninteractive \
    NODE_ENV=development \
    NEXT_TELEMETRY_DISABLED=1 \
    npm_config_update_notifier=false

WORKDIR /workspace

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# GitHub CLI
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
 && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
      | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
 && apt-get update \
 && apt-get install -y --no-install-recommends gh \
 && rm -rf /var/lib/apt/lists/*

USER node

# Claude Code
RUN curl -fsSL https://claude.ai/install.sh | bash

EXPOSE 3000 6006 9229

CMD ["bash"]

.env.local ファイルに GH_TOKEN 変数名で PAT（Personal Access Token）を記述。

devcontainer.json

Dockerfile を VS Code Dev Container と組み合わせるための設定ファイルです。

{
  "name": "FumiBlog Dev Container",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "features": {
    "ghcr.io/atsushi11o7/devcontainer-features/base-utils:2": {
      "locale": "C.UTF-8",
      "timezone": "Asia/Tokyo"
    }
  },
  "workspaceFolder": "/workspace",
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
  "runArgs": ["--env-file", "${localWorkspaceFolder}/.env.local"],
  "mounts": [
    "source=fumiblog-claude-config,target=/home/node/.claude,type=volume"
  ],
  "forwardPorts": [3000, 6006, 9229],
  "postCreateCommand": "test -f package.json && npm install || true",
  "containerEnv": {
    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
    "LANG": "C.UTF-8",
    "LC_ALL": "C.UTF-8"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss",
        "GitHub.vscode-pull-request-github"
      ]
    }
  },
  "remoteUser": "node",
  "updateRemoteUserUID": true
}

主要な項目はこんな感じです。

• features … 自前の dev container feature 、よく使うツールをまとめたもの（gitとかtzdataとか）
• runArgs: ["--env-file", "${localWorkspaceFolder}/.env.local"] … .env.local をコンテナ起動時に環境変数として読み込む。これでコンテンツを管理している microCMS のキーや GitHub PAT などをコンテナ内で参照
• mounts … ~/.claude を named volume にマウント。Claude Code の認証情報や設定 (.claude.json 等) はここに保存されるので、コンテナを rebuild しても消えない。
• postCreateCommand … 初回作成時に npm install を流して依存をセットアップ
• containerEnv … CLAUDE_CONFIG_DIR を /home/node/.claude に固定して、Claude Code が常に先ほどの永続ボリュームを見にいくようにしています。
• customizations.vscode.extensions … Claude Code 拡張、ESLint、Prettier、Tailwind CSS IntelliSense、GitHub PR 拡張をプリインストール
• forwardPorts … Dockerfile の EXPOSE と対応。VS Code が自動で port forwarding をかけてくれます。

MCP サーバ (.mcp.json)

リポジトリ直下の .mcp.json に書くと、このリポジトリで Claude Code を起動した時に自動でロードされる MCP サーバ群を定義できます。

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

今回は 2 つのサーバを入れています。

• context7 … Upstash の Context7 が提供する MCP サーバ。Next.js / React / Tailwind 等のライブラリの最新ドキュメントを Claude が必要に応じて取得できるようになります。
• github … Anthropic 公式の MCP server-github。GitHub API を Claude のツールとして公開してくれるので、Issue / PR / リポジトリ操作などを Claude から直接呼べます。

github サーバには PAT が必要なので、env ブロックで GITHUB_PERSONAL_ACCESS_TOKEN を渡しています。値は ${GITHUB_PERSONAL_ACCESS_TOKEN} の形でホスト側の環境変数（先ほど --env-file で読ませた .env.local）から展開されます。

2. gh skill コマンド

gh skill は 2026 年 4 月リリース の GitHub CLI v2.90 で追加されたサブコマンドです。これまで「リポジトリから SKILL.md を探してきてコピー」していた作業が、1 コマンドで完結するようになりました。

サブコマンド一覧

gh skill search <keyword>             # GitHub 全体から skill を検索
gh skill preview <repo> <skill>       # インストールせずに SKILL.md を表示
gh skill install <repo> <skill>       # ローカルに配置
gh skill update [--all]               # 入れた skill を更新
gh skill publish                      # 自作 skill を公開

配置先は --scope と --agent で決まる

ここが最初少し分かりにくかったのですが、

• --agent … どの AI ツール用か (claude-code, github-copilot, cursor 等)
• --scope … user（ホーム配下、全プロジェクト共通）か project（リポジトリ内）

の組み合わせで決まります。Claude Code 用にプロジェクト固有で入れるなら、次のようになります。

gh skill install <repo> <skill> --agent claude-code --scope project
# → /workspace/.claude/skills/<skill>/ に配置される

ちなみに --agent を省略するとデフォルトで github-copilot 扱いになるっぽいので、Claude Code で使う場合は必ず指定しましょう。

3. Anthropic 公式 skill を 3 つ導入

anthropics/skills には現在 17 個の公式 skill が用意されています。今回はその中から 3 つを選びました。

skill	用途
frontend-design	一番使ってみたかったやつ。UI を distinctive に作る指針 (タイポ・色・モーション等)
doc-coauthoring	文書共同執筆ワークフロー
skill-creator	自作 skill の作成・改善・評価

webapp-testing も気になりましたが、Playwright とかを別途入れる必要があったので一旦保留にしました。

導入は 1 コマンドで完了します。

gh skill install anthropics/skills frontend-design --agent claude-code --scope project
gh skill install anthropics/skills doc-coauthoring --agent claude-code --scope project
gh skill install anthropics/skills skill-creator    --agent claude-code --scope project

これで .claude/skills/<name>/ に配置されます。

4. CLAUDE.md と 自作 skill (dev-flow) について

CLAUDE.md に加えて、今回はブランチを切るところからPRを出すまでの一連の流れを記述したskill (dev-flow) を作成しました

役割分担

CLAUDE.md と skill で定義した内容についてです。

	CLAUDE.md	skill
読み込みタイミング	毎セッション自動	該当タスクに該当する時だけ
適用範囲	あらゆる作業	特定の workflow / 判断軸
入れる内容	プロジェクトの常時適用慣習	特定の一連の手順

例として整理すると以下のようになります。

CLAUDE.md (常時適用):
  - プロジェクト概要 (Next.js 16, Tailwind v4 ...)
  - Atomic Design 構造
  - コミット形式 (英語1行, Co-Authored-By なし)
  - ブランチ運用 (Git Flow 風)

dev-flow skill (workflow 時のみ):
  - branch 作成 → 変更 → commit → push → PR の手順
  - PR 本文の埋め方

skill が CLAUDE.md を参照する形にしておくと、コミット形式などの規約は CLAUDE.md に集約され、skill 側はスリムに保てるかなと思います。

CLAUDE.md は /init で叩き台を生成

Claude Code 標準の /init にリポジトリをスキャンさせて、CLAUDE.md の叩き台を作ってもらいました。

/init

返ってくる初稿はそのまま使えるレベルですが、Git Flow 運用の「develop がデフォルト base、main はリリース用」のような慣習レベルの文脈は補完が必要です。実際、最初の出力では Git Flow に触れていなかったので追記しました。

自作 skill は skill-creator で作る

skillを作るためのskillなんてあるのですね。skill-creator 、せっかくなので使用してみました。
skill-creator の SKILL.md には vibe mode という軽量モードが正式に許容されており、

Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

と書かれています。今回はお試しということもあり、評価ループ（evals/evals.json を作って with-skill / baseline 比較する正式モード）はスキップして、Capture Intent → 構成案 → SKILL.md ドラフトの 3 ステップだけで完成させました。

dev-flow skill の中身（抜粋）はこんな感じです。

---
name: dev-flow
description: |
  開発の標準ワークフローを一気通貫で実行する skill。
  develop からブランチを切る → 変更 → コミット → push → PR 作成 までをカバーする。
  「ブランチ切って」「PR 作って」「機能追加して PR お願い」など、変更からマージリクエスト
  までのフローを含む指示で必ず使う。
---

# Dev Flow (FumiBlog)

## 1. ブランチ作成
develop を最新化 → 分岐
- 命名: feature/* | fix/* | refactor/* | chore/* | docs/*

## 2. 変更
CLAUDE.md の Architecture / Theming セクションに従う

## 3. コミット
1行・英語 imperative・<72字・Co-Authored-By なし

## 4. Push & PR
gh pr create --base develop（.github テンプレ自動適用）

## 5. 報告
PR URL を返す

description を「少し pushy に書く」のがコツです。SKILL.md にも

please make the skill descriptions a little bit "pushy"

と書かれており、Claude には「under-trigger（trigger すべき場面で使わない）」の傾向があるため、明示しなくても発動するように描写を強めにしておく必要があります。

5. 実践: Hero セクションを skill にリファクタしてもらう

ここからが本番です。
ちょうどデザインが気に入らないHeroコンポーネントがあったのでこれをClaudeCodeに大規模修正してもらいます。

dev-flow に従ってブランチ作成

git fetch origin
git switch develop
git pull
git switch -c refactor/hero-section

dev-flow skill が自動でこの手順に沿ってくれます。Claude に「Hero リファクタするのでブランチ切って」と頼むだけで、develop の最新化から refactor/hero-section の作成までを一気にやってくれました。

frontend-design に従って方向性を決める

frontend-design skill は冒頭で BOLD aesthetic direction にコミットせよと要求してきます。Brutalist / Editorial / Retro-futuristic / Maximalist など 10 以上の方向性が例示されており、その中から 1 つを選ぶスタイルです。

既存ブログとの整合性を考え、Editorial-Tech / Brutalist を選択しました。

観点	Before	After
見出しフォント	sans-serif (Geist)	mono (Geist Mono)
見出しサイズ	text-4xl/5xl	text-4xl/6xl/7xl
強調語 "learnings"	紫グラデーション	solid cat-accent + 太め underline
背景の orb	indigo radial gradient	削除
装飾	レインボー幾何形状 12個	コーナー角ブラケット ┌─ ─┐ └─ ─┘ + 右側 hex index 列
ステータスライン	プレーン	[ ENGINEER ] 角括弧形式
フッター	なし	▶ COMPILED AT RUNTIME

こんな感じの提案が返ってきました。

「ターミナルの compiled output っぽさ」を全力で出す方向で、Inter や紫グラデーションといった "AI 風" の典型を全部排除する感じです。

ついでに、構造リファクタも合わせて実施しました。

最終的にこんな感じになりました

コミット → Push → PR

dev-flow skill の手順通りに、Push して PR を作成します。

以下の様な操作を自動的にやってくれます。

git push -u origin refactor/hero-section
gh pr create --base develop \
  --title "Refactor and redesign HeroSection (mono typography + terminal frame)" \
  --body "..."

事前に作成しておいた、.github/PULL_REQUEST_TEMPLATE.md (日本語、## 概要 ## 確認項目 の最小構成) が自動適用されます。

ここまで全部、Claude Code 内のチャットで「Hero をリファクタして PR まで作って」と頼むだけで完了しました。

こんな感じのPRが作成されました。

おわりに

正直、「skill って便利そうだけど別に無くてもそんな変わらないんじゃないか」と思っていたんですが、今回ちゃんと使ってみて考えが変わりました。

特に dev-flow みたいな「自分の開発手順」を丸ごと任せられるのは快適で、“AIにコードを書かせる”というよりは、“作業の流れごと委譲する”感覚に近いと思いました。
個人開発だとめんどくさがってPRを書かないですし、このあたりを強制的に回してくれるのはかなりありがたいです。

あと、frontend-design みたいな「思想を押し付けてくる系 skill」は、一貫性のないデザインを作ってしまう自分にとってかなり助かりますし、普通に面白かったです。

一方で、まだ「どういう単位で skill を切るのがいいか」は正直手探りなので、
今後はもう少し細かく分解したり、逆に大きめの workflow にまとめたりして試していこうと思っています。

しばらくは Claude Code + skill 前提で開発してみて、色々検証していく予定です。

リポジトリは atsushi11o7/fumiblog、Hero リファクタの PR は #2、リリース PR は #3 に置いてあるので、興味があれば覗いてみてください。