skill-studio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

开展结构化的JTBD访谈，明确要构建的内容、服务对象及构建原因，随后生成单页

design.md

design.svg

规格文档。该工具介于“我应该自动化这个吗？”（自动化顾问工具）和“我如何将其打包为Skill？”（Skill创建工具）之间。

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.

本Skill封装了一个可通过pip安装的外部CLI工具（

skill-studio

）。CLI工具负责会话状态管理、覆盖度跟踪和导出功能。Skill仅负责编排CLI工具，并不直接捆绑脚本。

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.

在以下任一情况触发：“帮我设计……”、“为……构建一个Skill”、“为……设计自动化流程”、“我想要一个能……的机器人/Agent/工作流”、“规划新的快捷方式”。当用户描述反复出现的痛点并询问如何自动化解决时，也可触发。

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>

系统PATH中需存在
```
skill-studio
```
CLI工具（在Skill目录内执行
```
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

。若命令未找到，从Skill的基础目录安装：

pip install -e <skill-studio-base-dir>

。

Interview protocol (text mode)

访谈流程（文本模式）

Follow these steps in order.

按以下步骤依次执行。

Step 0 — (Optional) Seed from a prior session

步骤0 —（可选）从历史会话导入

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:

bash

skill-studio propose-from-session <session_id>

若用户提供历史会话（Claude Code对话记录、其他skill-studio会话或任意对话记录路径），可基于该会话启动访谈，而非从头开始：

bash

skill-studio propose-from-session <session_id>

or: skill-studio propose-from-session --path <file>

或：skill-studio propose-from-session --path <file>

add --bundle-only to skip the LLM call and inspect the raw extract

添加 --bundle-only 参数可跳过LLM调用，直接查看原始提取内容


This runs in two stages:
1. **Deterministic ingest** (no LLM) — regex-extracts models tried, cost events, prompt changes, pain snippets, and hashes. A 50k-token transcript compresses to ~30 lines of JSON.
2. **Single LLM call** — over that compact bundle only, proposes a partial DesignJSON patch with a `rationale` map citing which signals justified each field.

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

`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.


此过程分为两个阶段：
1. **确定性导入**（无需LLM）——通过正则表达式提取尝试过的模型、成本事件、提示词变更、痛点片段及哈希值。一份50k token的对话记录可压缩为约30行JSON。
2. **单次LLM调用**——基于压缩后的内容，生成带有`rationale`映射的部分DesignJSON补丁，其中会注明每个字段的依据信号。

**生成的补丁不会自动应用**。需将补丁（含依据）展示给用户并请求批准。提供选项：`直接批准`、`在线编辑`、`丢弃并重新开始`、`部分批准`（保留部分字段，重新访谈其他字段）。

`propose-from-session`不会创建新会话。获得批准后，运行`new-session`（步骤1）创建会话，再将批准后的补丁通过管道传递给`apply-patch`，然后从下一个未覆盖的目标继续访谈循环。

Step 1 — Start the session

步骤1 — 启动会话

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:

bash

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.

预设类型：

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
```
——每个字段对应一个直接问题，无开场白。

运行命令：

bash

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

输出：

session_id: <uuid>
opening: <question text>

保存

session_id

。将开场问题以直接文本消息形式呈现给用户。

Step 2 — Interview loop

步骤2 — 访谈循环

For every user answer:

a. Extract a JSON patch. Emit a JSON object containing only the DesignJSON fields the answer addresses. Use only fields from the schema below — never hallucinate fields or values. If nothing schema-relevant was said, emit

{}

Example patch:

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"}

Example with list fields:

json

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

Example with object-list field (

scenarios

json

{"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 fields:

Field	Type	Notes
`hook`	str	One-sentence pitch of the automation
`problem.what_hurts`	str	Specific pain
`problem.cost_today`	str	What the pain costs right now
`needs.functional`	list[str]	What it must do
`needs.emotional`	list[str]	How the user wants to feel
`needs.social`	list[str]	Relational / status needs
`jtbd.situation`	str	When this happens
`jtbd.motivation`	str	What the user wants
`jtbd.outcome`	str	So they can...
`before_after.before_external`	str	Visible state before
`before_after.before_internal`	str	Felt state before
`before_after.after_external`	str	Visible state after
`before_after.after_internal`	str	Felt state after
`scenarios`	list[{title, vignette}]	Concrete day-in-the-life stories
`trigger.type`	`manual` / `scheduled` / `event`
`trigger.detail`	str	e.g. "7:45am weekdays"
`inputs`	list[str]	Data / services consumed
`capabilities`	list[str]	What it does
`outputs`	list[str]	What it produces
`guardrails`	list[str]	Safety rails; negative-space rules
`cta`	str	Next action at end of design
`concept_imagery.metaphor`	str	Visual / verbal handle

b. Apply the patch.

bash

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

Output:

coverage: 0.42
next_target: jtbd.situation

c. Check stop conditions. End the loop if either:

```
coverage >= threshold
```
(sprint=0.60, standard=0.80, deep=0.92)
User says "done", "wrap up", or "stop"

d. Ask the next question. Target the

next_target

field, in the active style. Never re-ask a field already past 0.5 coverage. Present the question as direct text to the user.

针对用户的每一条回答：

a. 提取JSON补丁。生成仅包含回答所涉及的DesignJSON字段的JSON对象。仅使用以下Schema中的字段——切勿虚构字段或值。若回答未涉及Schema相关内容，生成

{}

。

示例补丁：

json

{"jtbd.situation": "当我完成教练辅导电话后需要整理笔记", "problem.what_hurts": "手动记笔记需要20分钟，还会遗漏细节"}

列表字段示例：

json

{"needs.functional": ["转录音频", "提取行动项"], "guardrails": ["未经审核绝不发送笔记"]}

对象列表字段（

scenarios

）示例：

json

{"scenarios": [{"title": "辅导后赶时间", "vignette": "电话14:00结束，下一场会议14:15开始——我草草写下三个要点，到晚上就忘了其余内容。"}]}

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. 应用补丁

bash

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

输出：

coverage: 0.42
next_target: jtbd.situation

c. 检查终止条件。若满足以下任一条件，结束循环：

```
coverage >= 阈值
```
（sprint=0.60，standard=0.80，deep=0.92）
用户说“完成”、“结束”或“停止”

d. 提出下一个问题。针对

next_target

字段，采用当前选定的风格提问。切勿重复询问覆盖度已超过0.5的字段。将问题以直接文本形式呈现给用户。

Step 3 — Export

步骤3 — 导出

bash

skill-studio done <session_id>

Prints the paths to

design.md

and

design.svg

. Present both paths to the user.

bash

skill-studio done <session_id>

打印

design.md

和

design.svg

的路径。将两个路径告知用户。

Voice mode

语音模式

For voice interviews, skip the manual loop and delegate to the built-in pipeline:

bash

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

This spins up a Daily room (auto-opens in the browser), runs Groq Whisper STT -> interview loop -> Deepgram TTS, and auto-exports on session end.

If voice mode fails due to missing API keys, fall back to text mode and inform the user. To configure keys, run

skill-studio init

对于语音访谈，跳过手动循环，委托给内置管道：

bash

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

此命令会创建一个Daily房间（自动在浏览器中打开），运行Groq Whisper语音转文本 -> 访谈循环 -> Deepgram文本转语音，并在会话结束时自动导出结果。

若因缺少API密钥导致语音模式失败，fallback到文本模式并告知用户。要配置密钥，运行

skill-studio init

。

Other commands

其他命令

```
skill-studio list
```
— list all sessions

skill-studio export <id> md-svg

— regenerate

design.md

design.svg

```
skill-studio coverage <id>
```
— per-field confidence JSON
```
skill-studio next-target <id>
```
— ask-this-next hint
```
skill-studio init
```
— full first-run wizard (prereq checks + keys + paths)
```
skill-studio setup
```
— narrower key-rotation flow (sops-only)

```
skill-studio list
```
— 列出所有会话

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）

Sessions

会话存储

Each interview writes to

$SKILL_STUDIO_HOME/sessions/<uuid>/

(default:

~/.skill-studio/sessions/<uuid>/

```
design.json
```
— canonical schema (single source of truth)
```
transcript.md
```
— full Q&A log
```
design.md
```
,
```
design.svg
```
— exported artifacts

每次访谈的内容会写入

$SKILL_STUDIO_HOME/sessions/<uuid>/

（默认路径：

~/.skill-studio/sessions/<uuid>/

）：

```
design.json
```
— 标准Schema文件（唯一数据源）
```
transcript.md
```
— 完整问答记录
```
design.md
```
,
```
design.svg
```
— 导出的产物

Troubleshooting

故障排除

skill-studio: command not found
— Run

pip install -e <skill-studio-base-dir>

and retry.

apply-patch
returns an error — Verify the JSON patch is valid (keys must match schema fields above). Run
```
skill-studio coverage <session_id>
```
to inspect current state.
Session not found — Always run
```
new-session
```
before the first
```
apply-patch
```
. There is no implicit session creation. Run
```
skill-studio list
```
to check existing sessions.
Voice mode key errors — Run
```
skill-studio init
```
to configure missing keys, or fall back to text mode.

skill-studio: command not found
— 运行

pip install -e <skill-studio-base-dir>

后重试。

apply-patch
返回错误 — 验证JSON补丁是否有效（键必须与上述Schema字段匹配）。运行
```
skill-studio coverage <session_id>
```
查看当前状态。
会话未找到 — 首次运行
```
apply-patch
```
前必须先运行
```
new-session
```
。不会自动创建会话。运行
```
skill-studio list
```
检查现有会话。
语音模式密钥错误 — 运行
```
skill-studio init
```
配置缺失的密钥，或改用文本模式。

Notes

注意事项

The interview loop runs entirely inside Claude Code for text mode. No Anthropic API key is required.
Voice mode LLM provider is swappable via
```
LLM_PROVIDER=anthropic
```
(default is
```
openrouter
```
).

文本模式下，访谈循环完全在Claude Code内运行，无需Anthropic API密钥。
语音模式的LLM提供商可通过
```
LLM_PROVIDER=anthropic
```
切换（默认使用
```
openrouter
```
）。