skill-studio

Skill Studio

目的

構築するもの、対象者、その理由を把握するために、構造化されたJTBDインタビューを実施し、1ページのdesign.md＋design.svg仕様書を出力します。「これを自動化すべきか？」（automation-advisor）と「これをスキルとしてどのようにパッケージ化するか？」（skill-creator）の間に位置します。

アーキテクチャ

このスキルは、pipでインストールする外部CLIツール（skill-studio）をラップします。CLIがセッション状態、カバレッジの追跡、エクスポートを処理します。このスキルはCLIをオーケストレーションし、スクリプトを直接同梱することはありません。

使用するタイミング

次のいずれかの依頼があった場合に起動します：「設計を手伝って……」「……向けのスキルを作って」「……を自動化する仕組みを設計して」「……するボット／エージェント／ワークフローが欲しい」「新しいショートカットの範囲を決めて」。また、ユーザーが繰り返し発生する困りごとを説明し、自動化の方法を尋ねた場合も起動します。

セッション分析の依頼があった場合も起動します：「このセッションを分析して」「ここからどんなスキルを作れる？」「セッションからスキルを提案して」「どんなワークフローを使った？」「このセッションで何をした？」「作業からパターンを抽出して」「このセッションをスキルにして」「ここから自動化できることは？」。ユーザーがセッションIDに言及した場合や、サブエージェントの動作について尋ねた場合も、このスキルが対応します。

前提条件

• PATH上にskill-studio CLIがあること（スキルディレクトリ内でpip install -e .を実行するか、skill-studio initでガイドに沿ってセットアップ）
• Python 3.11+
• テキストモードではAPIキーは不要です。インタビューはClaude Code内で直接実行されます
• 音声モード（--voice）では、DAILY_API_KEY、GROQ_API_KEY、DEEPGRAM_API_KEY、およびLLMプロバイダーキー（デフォルトはOPENROUTER_API_KEY）が必要です。キーが不足している場合は、代わりにテキストモードを提案してください。

CLIが利用可能か確認するには、skill-studio --helpを実行してください。コマンドが見つからない場合は、スキルのベースディレクトリからインストールしてください：pip install -e <skill-studio-base-dir>。

インタビュープロトコル（テキストモード）

以下の手順を順番に実行してください。

ステップ0 — （任意）過去のセッションから情報を取り込む

ユーザーが過去のセッション（Claude Codeのトランスクリプト、別のskill-studioセッション、または任意のトランスクリプトのパス）を提供した場合は、何もない状態から始める代わりに、その情報を取り込んでインタビューを開始します：

# Analyze the current running session
skill-studio propose-from-session --current

# Analyze a specific session by ID (prefix match works)
skill-studio propose-from-session <session_id>

# Analyze a session from a specific project
skill-studio propose-from-session <session_id> --project <project-dir-name>

# Analyze an arbitrary transcript file
skill-studio propose-from-session --path <file>

# Inspect the raw extracted bundle without an LLM call
skill-studio propose-from-session --current --bundle-only

これは2段階で実行されます：

1. 決定論的な取り込み（LLMなし）— 試したモデル、コストイベント、プロンプトの変更、問題点の抜粋、サブエージェントの呼び出し（説明、タイプ、プロンプトの抜粋を含むAgentツール）、スキルの呼び出し、ツールの実行順序（すべてのツール呼び出しの順序付きリスト）、ツールの使用頻度、ワークフローパターン（繰り返される複数ツールの実行順序）を抽出します。5万トークンのトランスクリプトは、コンパクトな構造化JSONバンドルに圧縮されます。
2. 単一のLLM呼び出し — このコンパクトなバンドルのみを使い、各フィールドの根拠となったシグナルを記したrationaleマップ付きの部分的なDesignJSONパッチに加え、観測されたワークフローパターンやエージェントのオーケストレーションから導き出した新しいスキルの候補となるスキル提案を作成します。

バンドルには、次の構造化シグナルが含まれます：

• agents — description、subagent_type、prompt_snippetを含むサブエージェントの呼び出し
• skills — セッション中に確認されたスキルの呼び出し
• tool_sequence — 説明付きのすべてのツール呼び出しを順番に並べたリスト
• tool_frequency — 各ツールの使用頻度
• workflow_patterns — 繰り返されるツールの実行順序（例：「Read → Edit → Bash」が3回現れた場合、テストと修正のサイクルを示唆します）

提案は自動的には適用されません。 根拠とスキル提案を添えてユーザーに提示し、承認を求めてください。選択肢として、そのまま承認、インラインで編集、破棄して最初から開始、一部を承認（一部のフィールドを保持し、残りを再インタビュー）を提示してください。

提案にskill_proposalsが含まれる場合は、それらを別途提示し、いずれかを使って/skill-creatorに進むかユーザーに尋ねてください。

propose-from-sessionはセッションを作成しません。承認後、new-session（ステップ1）を実行してセッションを作成し、承認されたパッチをapply-patchに渡してから、次に未対応の項目を起点としてインタビューループを続けてください。

Claude Codeのセッションを参照する

分析対象のセッションをユーザーが選べるようにするには：

# List recent sessions (most recent first, all projects)
skill-studio list-sessions

# Filter to a specific project
skill-studio list-sessions --project <project-dir-name>

# Show more results
skill-studio list-sessions --limit 50

出力には、セッションIDのプレフィックス、経過時間、サイズ、タイトルが表示されます。

ステップ 1 — セッションを開始する

プリセット：ai-agent（デフォルト）、life-automation、knowledge-work、custom。 深度：sprint（0.60、約5～7問）、standard（0.80、約15～20問、デフォルト）、deep（0.92、約25～35問）。

スタイル（質問の表現方法を決めます）：

• scenario-first（デフォルト）— 「具体的な場面をひとつ教えてください。そのときのことを順に説明してください……」
• socratic — 「なぜそれが重要なのでしょうか？ もし……だったら、どうなるでしょうか？」
• metaphor-first — 「この自動化を何かにたとえると、何になるでしょうか？」
• form — 前置きなしで、項目ごとに直接質問します。

実行します：

skill-studio new-session --preset <preset> --depth <depth> --style <style>

出力：

session_id: <uuid>
opening: <question text>

session_idを保存します。最初の質問を、ユーザーに直接テキストメッセージとして提示します。

ステップ 2 — インタビューのループ

ユーザーの回答ごとに、次の処理を行います。

a. JSON パッチを抽出します。 回答で触れられた DesignJSON フィールドのみを含む JSON オブジェクトを出力します。以下のスキーマにあるフィールドのみを使用し、フィールドや値を決して捏造しないでください。スキーマに関連する情報がなければ、{}を出力します。

パッチの例：

{"jtbd.situation": "When I finish a coaching call and need to write up notes", "problem.what_hurts": "Manual note-taking takes 20 minutes and I lose details"}

リストフィールドを含む例：

{"needs.functional": ["transcribe audio", "extract action items"], "guardrails": ["never send notes without review"]}

オブジェクトリストフィールド（scenarios）を含む例：

{"scenarios": [{"title": "Post-coaching rush", "vignette": "Call ends at 14:00, next meeting at 14:15 — I scribble three bullet points and lose the rest by evening."}]}

DesignJSON フィールド：

フィールド	型	注記
hook	str	自動化を一文で表す説明
problem.what_hurts	str	具体的な悩み
problem.cost_today	str	現時点で、その悩みによって生じているコスト
needs.functional	list[str]	必要な機能
needs.emotional	list[str]	ユーザーが望む感情
needs.social	list[str]	対人関係上のニーズ／ステータス上のニーズ
jtbd.situation	str	これが起きる状況
jtbd.motivation	str	ユーザーが望むこと
jtbd.outcome	str	その結果、ユーザーができるようになること
before_after.before_external	str	作業前に目に見える状態
before_after.before_internal	str	作業前に感じている状態
before_after.after_external	str	作業後に目に見える状態
before_after.after_internal	str	作業後に感じている状態
scenarios	list[{title, vignette}]	日常の具体的なシナリオ
trigger.type	manual / scheduled / event
trigger.detail	str	例：「平日の午前7時45分」
inputs	list[str]	取り込むデータ／サービス
capabilities	list[str]	実行する内容
outputs	list[str]	生成するもの
guardrails	list[str]	安全策、実行しないことのルール
cta	str	デザインの最後に示す次のアクション
concept_imagery.metaphor	str	視覚的／言語的な表現の手がかり

b. パッチを適用します。

echo '<patch_json>' | skill-studio apply-patch <session_id>

出力：

coverage: 0.42
next_target: jtbd.situation

c. 停止条件を確認します。 次のいずれかに該当したら、ループを終了します。

• coverage >= threshold（sprint=0.60、standard=0.80、deep=0.92）
• ユーザーが「done」「wrap up」「stop」と言った場合

d. 次の質問をします。 有効なスタイルで、next_targetフィールドを対象にします。カバー率がすでに0.5を超えているフィールドは、決して再度質問しないでください。質問はユーザーに直接テキストで提示します。

ステップ 3 — エクスポート

skill-studio done <session_id>

design.mdとdesign.svgへのパスを出力します。両方のパスをユーザーに提示します。

音声モード

音声インタビューでは、手動ループを省略し、組み込みパイプラインに委任します。

skill-studio new --voice --preset <preset> --depth <depth>

Daily ルームを起動し（ブラウザーで自動的に開きます）、Groq Whisper STT -> インタビューループ -> Deepgram TTS を実行し、セッション終了時に自動でエクスポートします。

API キーがないために音声モードが失敗した場合は、テキストモードに切り替えてユーザーに知らせます。キーを設定するには、skill-studio initを実行します。

その他のコマンド

• skill-studio list — skill-studio のすべてのインタビューセッションを一覧表示します
• skill-studio list-sessions — Claude Code のセッションを一覧表示します（新しい順）
• skill-studio list-sessions --project <name> — プロジェクトで絞り込みます
• skill-studio export <id> md-svg — design.md + design.svgを再生成します
• skill-studio coverage <id> — フィールドごとの信頼度を JSON で表示します
• skill-studio next-target <id> — 次に質問する項目のヒントを表示します
• skill-studio init — 初回セットアップ用のウィザードを実行します（前提条件の確認 + キー + パス）
• skill-studio setup — キーをローテーションするための、より限定的な手順を実行します（sops のみ）

セッション

各インタビューは $SKILL_STUDIO_HOME/sessions/<uuid>/ に保存されます（デフォルト：~/.skill-studio/sessions/<uuid>/）。

• design.json — 正規スキーマ（唯一の信頼できる情報源）
• transcript.md — 質疑応答の全ログ
• design.md、design.svg — エクスポートされた成果物

トラブルシューティング

• skill-studio: command not found — pip install -e <skill-studio-base-dir> を実行してから、再試行してください。
• apply-patch がエラーを返す — JSON パッチが有効であることを確認してください（キーは上記のスキーマフィールドと一致している必要があります）。skill-studio coverage <session_id> を実行して現在の状態を確認してください。
• セッションが見つからない — 最初の apply-patch の前に、必ず new-session を実行してください。暗黙的にセッションが作成されることはありません。skill-studio list を実行して既存のセッションを確認してください。
• 音声モードのキーエラー — skill-studio init を実行して不足しているキーを設定するか、テキストモードに切り替えてください。

注意事項

• テキストモードでは、インタビューループはすべて Claude Code 内で実行されます。Anthropic API キーは必要ありません。
• 音声モードの LLM プロバイダーは LLM_PROVIDER=anthropic で切り替えられます（デフォルトは openrouter です）。