Skill Studio

Skill Studio

Purpose

Conduct a structured JTBD interview that captures what to build, for whom, and why — then emit a one-page design.md + design.svg spec. Sits between "should I automate this?" (automation-advisor) and "how do I package this as a skill?" (skill-creator).

Architecture

This skill wraps an external CLI tool (skill-studio) installed via pip. The CLI handles session state, coverage tracking, and export. The skill orchestrates the CLI — it does not bundle scripts directly.

When to use

Trigger on any of: "help me design...", "build a skill for...", "design an automation for...", "I want a bot/agent/workflow that...", "scope a new shortcut". Also trigger when the user describes a recurring pain and asks how to automate it.

Also trigger for session analysis: "analyze this session", "what skills could I build from this", "propose skills from session", "what workflows did I use", "what did I do in this session", "extract patterns from my work", "turn this session into a skill", "what could be automated from this". If the user references a session ID or asks about subagent activity, this skill handles it.

Prerequisites

• skill-studio CLI on PATH (pip install -e . inside the skill directory, or skill-studio init for guided setup)
• Python 3.11+
• Text mode needs no API key — the interview runs natively inside Claude Code
• Voice mode (--voice) needs DAILY_API_KEY, GROQ_API_KEY, DEEPGRAM_API_KEY, and an LLM provider key (OPENROUTER_API_KEY by default). If any key is missing, suggest text mode instead.

To verify the CLI is available, run skill-studio --help. If the command is not found, install it from the skill's base directory: pip install -e <skill-studio-base-dir>.

Interview protocol (text mode)

Follow these steps in order.

Step 0 — (Optional) Seed from a prior session

If the user provides a prior session (Claude Code transcript, another skill-studio session, or arbitrary transcript path), seed the interview instead of starting blank:

# 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

This runs in two stages:

1. Deterministic ingest (no LLM) — extracts models tried, cost events, prompt changes, pain snippets, subagent calls (Agent tool with descriptions, types, prompt snippets), skill invocations, tool sequences (ordered list of all tool calls), tool frequency, and workflow patterns (repeated multi-tool sequences). A 50k-token transcript compresses to a compact structured JSON bundle.
2. Single LLM call — over that compact bundle only, proposes a partial DesignJSON patch with a rationale map citing which signals justified each field, plus skill proposals — potential new skills derived from observed workflow patterns and agent orchestration.

The bundle includes these structured signals:

• agents — subagent calls with description, subagent_type, and prompt_snippet
• skills — skill invocations observed during the session
• tool_sequence — ordered list of all tool calls with descriptions
• tool_frequency — how often each tool was used
• workflow_patterns — repeated tool sequences (e.g. "Read → Edit → Bash" appearing 3× suggests a test-fix cycle)

The proposal is NOT applied automatically. Present it to the user (with the rationale and any skill proposals) and ask for approval. Offer: approve as-is, edit inline, discard and start fresh, approve partial (keep some fields, re-interview others).

If the proposal includes skill_proposals, present them separately and ask if the user wants to proceed to /skill-creator with any of them.

propose-from-session does not create a session. After approval, run new-session (Step 1) to create one, then pipe the approved patch to apply-patch, and continue the interview loop from the next uncovered target.

Browsing Claude Code sessions

To help the user pick a session to analyze:

# 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

Output shows session ID prefix, age, size, and title.

Step 1 — Start the session

Presets: ai-agent (default), life-automation, knowledge-work, custom. Depth: sprint (0.60, ~5–7 questions), standard (0.80, ~15–20 questions, default), deep (0.92, ~25–35 questions).

Styles (shape how questions are phrased):

• scenario-first (default) — "Walk me through a specific time when..."
• socratic — "Why does that matter? What would happen if...?"
• metaphor-first — "If this automation were a [thing], what would it be?"
• form — One direct question per field, no preamble.

Run:

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

Output:

session_id: <uuid>
opening: <question text>

Store the session_id. Present the opening question to the user as a direct text message.