Skills化を見送った話：飛びつかない勇気

AI エージェントの「使いにくさ」

DevLoopRunner という Web アプリを開発しています。GitHub Issue を起点に、AI エージェントが要件定義から実装、テスト、ドキュメント作成まで自動で回してくれるツールです。

バックエンドは Node.js の CLI として実装しており、Claude（AI）に実行させています。Claude Code というツールでリポジトリを開くと、AI が自動的にコマンドを実行してくれる仕組みです。

このツール、便利なのですが、使うたびにストレスを感じていました。

例えば、新しい Issue でワークフローを開始するとき。こういうコマンドを実行する必要があります。

node dist/index.js init \
  --issue-url https://github.com/tielec/ai-workflow-agent/issues/123 \
  --base-branch main \
  --language ja

一見シンプルですが、実際には：

• --issue-url の URL を毎回コピペ
• --base-branch はデフォルトで main だけど、毎回指定
• --language も毎回 ja を指定

「あれ、このオプション何だっけ？」となることも多く、毎回 CLAUDE.md（AI への指示書）を確認していました。

フェーズ実行のコマンドはもっと複雑です。

node dist/index.js execute \
  --issue 123 \
  --preset review-design \
  --agent auto \
  --codex-model max \
  --claude-model opus \
  --auto-model-selection

--preset って何があったっけ？ --agent は auto でいいんだっけ？ --codex-model と --claude-model の違いは？

毎回確認して、毎回迷う。

正直、面倒でした。

「Skills」という仕組みを知った

「もっと良い方法があるはず」と思いながら、Claude Code の最新機能を調べてみました。

そこで出会ったのが Skills という仕組みです。

Skills は、ざっくり言うと「AI に覚えさせる専用コマンド」です。~/.claude/skills というフォルダにコマンドの説明を書いておくと、/コマンド名 という形で呼び出せるようになります。

例えば、こんな感じです。

~/.claude/skills/init-workflow/
└── SKILL.md  # コマンドの説明を書く

これを作っておくと、/init-workflow と打つだけで、AI が：

1. Issue 番号を聞いてくる
2. デフォルト値を提案してくれる
3. 対話的に選択できる
4. 確認してから実行

という流れで進めてくれます。

「これ、めちゃくちゃ良いのでは？」と思いました。

Before/After：どう変わるのか

具体的にどう変わるのか、実際の使用例で比較してみます。

現在の使い方

ユーザー: 「Issue #123 のワークフローを開始したい」

Claude: 「CLAUDE.md を確認します...
        init コマンドを使いますね。
        オプションは... --issue-url が必要で...
        --base-branch も... --language も...」

        node dist/index.js init \
          --issue-url https://github.com/tielec/ai-workflow-agent/issues/123 \
          --base-branch main \
          --language ja

        実行しますか？

ユーザー: 「はい」

（実行）

毎回この長いコマンドを確認して、承認する必要があります。

Skills 化後のイメージ

ユーザー: 「Issue #123 のワークフローを開始して」

Claude: 「/init-workflow を使いますね」

        Issue 番号を教えてください: 123

        設定を確認します：
        ✓ リポジトリ: tielec/ai-workflow-agent（自動検出）
        ✓ ブランチ名: ai-workflow/issue-123（自動生成）
        ✓ ベースブランチ: main（デフォルト）
        ✓ 言語: ja（デフォルト）

        この設定で実行しますか？ [Y/n]

ユーザー: 「y」

（実行）

変わったポイント：

1. コマンドが短い: /init-workflow だけ
2. 対話的: Issue 番号を聞いてくる
3. デフォルト値: よく使う設定を自動的に埋めてくれる
4. 確認が楽: 設定を一覧で確認できる

もう一つ、フェーズ実行の例も見てみます。

現在：オプション地獄

ユーザー: 「Planning から Design まで実行して」

Claude: 「CLAUDE.md を確認します...
        review-design プリセットがありますね。
        auto-model-selection は有効にしますか？
        agent は auto でいいですか？
        codex-model は...」

        node dist/index.js execute \
          --issue 123 \
          --preset review-design \
          --agent auto \
          --codex-model max \
          --claude-model opus \
          --auto-model-selection

        実行しますか？

ユーザー: （オプション多すぎて確認が大変...）

Skills 化後のイメージ

ユーザー: 「Planning から Design まで実行して」

Claude: 「/execute-phase を使いますね」

        Issue #123 を検出しました

        プリセット: review-design
        実行フェーズ: Planning → Requirements → Design

        推奨設定:
        ✓ auto-model-selection: ON（難易度に応じて自動選択）
        ✓ agent: auto（Codex 優先、失敗時は Claude に自動切替）
        ✓ codex-model: max（最高性能モデル）
        ✓ claude-model: opus（最高性能モデル）

        設定を変更しますか？ [y/N]

ユーザー: 「n」

（実行）

推奨設定を提案してくれるので、特にこだわりがなければそのまま進められます。変更したいときだけカスタマイズすればいい。

これなら、毎回オプションを確認する手間が減ります。

Subagent という機能も見つけた

Skills について調べていると、もう一つ気になる機能がありました。Subagent です。

Subagent は、複数のタスクを並列実行できる仕組みです。最大10個まで同時に動かせるとのこと。

「これはもしかして...」と思いました。

DevLoopRunner では、Phase 0（Planning）から Phase 7（Documentation）まで順次実行しています。もし並列実行できれば、実行時間を大幅に削減できるのではないか？

期待効果を試算してみました。

項目	現在	Subagent 活用後	改善率
Phase 0-2 実行時間	45分	15分	67% 削減
auto-issue 実行時間	30分	10分	66% 削減

67% 削減！ これはすごい。

ただ、冷静に考えてみると、Phase 0-2 には依存関係があります。

Phase 0 (Planning)
  ↓ 成果物を参照
Phase 1 (Requirements)
  ↓ 成果物を参照
Phase 2 (Design)

Planning の成果物がないと Requirements は書けません。Requirements の成果物がないと Design は書けません。

並列実行できないじゃないか。

さらに、既存のアーキテクチャを見直してみると、実は各フェーズは既に「専門化されたエージェント」として動いていました。独立したプロンプトを持ち、必要な情報だけを渡し、独立した出力を生成する。

Subagent の主要な機能は、既に実現されていたのです。

実際に並列化できるのは：

• auto-issue の3カテゴリ（bug, refactor, enhancement）
• PR コメントの複数件処理

ただ、これらの処理時間は現状でも比較的短く、「遅くて困っている」という状況ではありません。

最終判断：全部見送ることにした

ここまで検討してきましたが、最終的に Skills 化も Subagent も全部見送る ことにしました。

理由は単純で、まだ使いこなせないと判断したからです。

Skills 化を見送った理由

Skills は確かに便利そうです。コマンドが短くなり、デフォルト値が埋まり、対話的に選択できる。

ただ、実際に Skills を書いてみようとすると、いくつか疑問が出てきました。

• Skills の YAML frontmatter の書き方がよくわからない
• context: fork とか hooks とか、どう使えばいいのか
• 既存の CLAUDE.md とどう共存させるのか
• エラーが起きたときのデバッグはどうするのか

公式ドキュメントを読んでも、「なんとなくわかる」程度で、「これで完璧」という自信が持てませんでした。

正直、もうちょっと勉強が必要です。

Subagent を見送った理由

Subagent も同様です。並列実行の仕組みは理解できましたが、実際にどう実装するのかがイメージできませんでした。

• 既存のアーキテクチャをどう変更するのか
• エラーハンドリングはどうするのか
• デバッグはどうするのか
• 本当に期待通りの効果が出るのか

実装のリスクと効果を天秤にかけると、今の段階で飛びつくには早いと感じました。

慎重な判断の重要性

「新しい技術を使いたい」という気持ちは強くありました。ただ、使いこなせないまま導入すると、かえって複雑さが増してしまいます。

現状の CLAUDE.md は確かに長大ですが、少なくとも動いています。安定しています。

それを壊してまで新しい仕組みに移行する必要があるのか？ 冷静に考えると、今はその時期ではないと判断しました。

学び：飛びつかない勇気

この検討プロセスで学んだことは3つあります。

1. 「便利そう」と「使いこなせる」は別

新しい技術を見ると、「これは便利そうだ」と思います。ただ、実際に使いこなせるかどうかは別の話です。

• ドキュメントを読んで理解できるか
• 実装のイメージが湧くか
• エラーが起きたときに対処できるか

これらが「Yes」と言えないなら、まだ早いということです。

2. 現状の設計を過小評価しない

「新しい技術で全部解決」と思いがちですが、既存の設計にも価値があります。

DevLoopRunner の各フェーズは、実質的にサブエージェントとして機能していました。Skills がなくても、CLAUDE.md で十分に動いています。

現状を過小評価せず、「本当に変える必要があるのか？」を問い直すことが大切です。

3. 「勉強してから」という選択肢

「今すぐ導入しなければ」と焦る必要はありません。「もうちょっと勉強してから」という選択肢もあります。

Skills や Subagent は、逃げません。ドキュメントを読み、サンプルを試し、理解が深まってから導入しても遅くありません。

飛びつかない勇気も、時には必要です。

おわりに

Claude Code 2.1.0 の新機能を調べ、Skills 化と Subagent を検討しました。

どちらも魅力的な機能でしたが、最終的に全部見送ることにしました。理由は、まだ使いこなせないと判断したからです。

「新しい技術を使いたい」という気持ちと、「本当に使いこなせるか？」という冷静な判断。このバランスを取ることが、結局は良い意思決定につながるのだと思います。

もうちょっと勉強してから、改めて検討します。

---

関連書籍

Claude Code や AI 開発ツールについてより深く学びたい方へ：

[📦 商品リンク: moshimo-book-9CeFY]

[📦 商品リンク: moshimo-book-fINTJ]