Skill 設計方法論：スクリプトと LLM の分割技法

チャット型ワークフローの問題

多くの人はこう使っている：

あなた：「ニュースレターを作って」
// Claude がゼロから理解、ゼロから実行
// 毎回品質が異なる、ステップが抜ける

あなた：「もう一回」
// またゼロから...

3つの根本的な問題：

不安定 — 同じ指示でも毎回品質が異なる
トークンの無駄 — 毎回フロー全体を再理解
蓄積できない — うまくいった回は次のセッションで忘れ去られる

発想の転換

「AI とチャットしている」のではない。

あなたは組立ラインを設計している。

ラインの一部はロボットアーム（確定的スクリプト）、一部は人間の作業員（LLM 判断）。Skill はこの組立ラインを固定化するもの。

コア分割：スクリプト vs LLM

すべてのワークフローは2種類のステップに分解できる：

	スクリプト（確定的）	LLM（動的）
本質	毎回同じ	文脈に応じた判断が必要
例	API呼び出し、ファイル操作、ビルドコマンド	内容分析、創造的決定、翻訳
Skill 内では	スクリプトを書き、LLM は実行するだけ	判断フレームワークを記述
安定性	100% 予測可能	プロンプト品質で制御

重要な洞察：

スクリプトで書けるなら、LLM の頭脳を使わせるな。 LLM の価値は「結果の橋渡し」と「重要な判断」にある。

リズム：スクリプトが結果を取得 → LLM が分析・判断 → 次のスクリプト実行 → LLM が再判断。

Skill はこのリズムを固定化する。

3ステップ分析法

Step 1：全ステップを列挙

要件を5-10個の具体的ステップに分解する。分類はまだ気にしない。

Step 2：各ステップにマーク

自分に問う：「このステップはスクリプトで書けるか？」

はい → スクリプトを書く。LLM は実行して結果を取るだけ
いいえ → LLM が頭を使うべき場所。判断フレームワークを与える

Step 3：Skill に組み立て

スクリプトステップ → 実際のコード（Python、Bash、API呼び出し）
LLM ステップ → 判断フレームワーク（基準、制約、例）

実践例：バージョン更新トラッカー

要件：「Claude Code のリリースを自動追跡し、新バージョンで記事を書き、3言語で公開」

Step 1 — ステップの列挙：

最新バージョン番号を確認
既知バージョンと比較
changelog を取得
どの変更がユーザーにとって重要か分析
記事の切り口とタイトルを決定
指定フォーマットで記事を執筆
3言語に翻訳
対応ディレクトリに保存

Step 2 — 各ステップにマーク：

ステップ	タイプ	理由
1. 最新バージョン確認	スクリプト	`gh api` 1行で完了
2. バージョン比較	スクリプト	Python 文字列比較
3. changelog 取得	スクリプト	WebFetch で固定URL
4. 重要な変更を分析	LLM	意味理解が必要
5. 切り口・タイトル決定	LLM	創造性が必要
6. フォーマットで執筆	混合	テンプレート固定、内容は動的
7. 3言語翻訳	LLM	言語能力が必要
8. ファイル保存	スクリプト	パスルール固定

Step 3 — Skill として記述：

スクリプトステップ — LLM にスクリプトを実行させる：

## ステップ 1：最新バージョン確認
## 以下の Bash を実行、結果を $LATEST_VERSION に保存
gh api repos/anthropics/claude-code/releases/latest \
  --jq '.tag_name'

## ステップ 2：バージョン比較
## 以下の Python スクリプトを実行
known = open('last-known-version.txt').read().strip()
if known == latest:
    print("NO_UPDATE")
    sys.exit(0)

LLM ステップ — 判断フレームワークを与える：

## ステップ 4：変更の分析
## 前のスクリプトで changelog のテキストを取得済み
## ここで LLM が意味を理解する必要がある
以下の優先度で分類：
  高：日常使用に影響する機能変更
  中：新しい CLI コマンドやパラメータ
  低：バグ修正（重大でない限り）
最も注目すべき 3-5 点をリストアップ。

## ステップ 5：タイトル決定
## 創造性が必要 — スクリプトでは良いタイトルは作れない
フォーマット：Claude Code vX.Y.Z: {一言のハイライト}
切り口：読者に「あなたにとっての意味」を伝える

動的ステップの安定化

LLM ステップは野放しではない。3つのテクニックで安定させる：

1. 品質ゲート

>= 80 → 合格
60-79 → 自動修正して再評価
< 60  → 停止、人間にエスカレーション

2. 例を与える（Few-shot）

良い：「v2.1.37: Agent Teams が Split-Pane モードを正式サポート」
悪い：「Claude Code が更新された」
悪い：「複数の重要な改善と修正を含む」

3. さらに細かく分割

動的ステップが大きすぎて結果が不安定なら — さらに分割する。

大きすぎ：「changelog を分析して記事を書く」

分割：
  1. 全変更項目をリスト化        （単純なリスト化）
  2. 各項目を 1-5 で評価         （構造化スコアリング）
  3. 上位 3 項目について執筆     （範囲の絞り込み）

原則：動的ステップが小さく、制約が明確であるほど → 結果は安定する。

その他の例

ステップ	タイプ	ツール
ニュースソース取得	スクリプト	WebFetch / RSS
書く価値があるか判断	LLM	関連性判断
ポイント分析・切り口決定	LLM	理解 + 創造性
テンプレートで記事作成	混合	テンプレート + LLM が内容を埋める
articles/ に保存	スクリプト	固定パス
Threads API で投稿	スクリプト	threads-post.js

今日のスケジュール → 資料準備

ステップ	タイプ	ツール
カレンダー API に問い合わせ	スクリプト	Google Calendar API
各会議のテーマを理解	LLM	意味理解
関連ファイルを検索	スクリプト	Glob / Grep
どの資料が関連するか判断	LLM	関連性判断
要約を整理・優先順位付け	LLM	統合 + ランキング

メール処理

ステップ	タイプ	ツール
未読メールを取得	スクリプト	IMAP / Gmail API
分類：重要 / 通常 / スパム	LLM	内容理解
重要メールの要約	LLM	要約能力
返信の下書き作成	LLM	文章作成
返信を送信	スクリプト	Resend / SMTP

パターンは常に同じ：スクリプトが収集 → LLM が理解 → スクリプトが実行。

Skill ファイルフォーマット

# .claude/skills/my-skill/SKILL.md
---
name: ecosystem-update
description: >
  バージョン更新を追跡し記事を自動執筆。
  Triggers: "check update", "new version"
version: 0.1.0
allowed-tools:
  - Read
  - Write
  - Bash
  - WebFetch
  - Task
user-invocable: true     # /ecosystem-update でトリガー
context: fork            # 独立コンテキスト
agent: content-writer    # 特定の Agent に委譲
model: sonnet            # モデル指定
---

# 以下がワークフロースクリプト（Markdown）
# 固定ステップ + 動的ステップを交互に配置

重要なフィールド：

context: fork — 独立コンテキストで実行、メイン会話のトークンを消費しない
agent — 指定した Agent 定義ファイルに実行を委譲
allowed-tools — この Skill が使用できるツールのホワイトリスト

思考モデル

要件を受け取る
    ↓
全ステップを列挙
    ↓
各ステップに問う：「スクリプトで書けるか？」
    ↓
  はい → スクリプトを書く（LLM は実行して結果を取るだけ）
  いいえ → LLM に任せる（判断基準 + 制約 + 例を与える）
    ↓
Skill に組み立て
    ↓
テスト → LLM ステップが不安定？→ さらに分割 / 制約を追加
    ↓
安定した自動化ワークフロー ✓

設計の心得

すべてのワークフローは Skill 化できる
スクリプトで書けるなら、LLM に考えさせるな
LLM の価値は「結果の橋渡し」と「重要な判断」にある
LLM の判断が不安定？さらに細かく分割、例を追加、品質ゲートを設置
まず1つの Skill から始めて、うまくいったら拡張する