skill-studio

Skill Studio

用途

开展结构化的 JTBD 访谈，了解要构建什么、面向谁以及原因，然后生成一页式 design.md + design.svg 规格。它位于“我该不该自动化这件事？”（automation-advisor）与“如何将它打包成一项技能？”（skill-creator）之间。

架构

此技能封装了一个通过 pip 安装的外部 CLI 工具（skill-studio）。该 CLI 负责会话状态、覆盖情况跟踪和导出。此技能负责协调 CLI，不会直接捆绑脚本。

适用场景

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

会话分析场景也要触发：“分析此会话”“我可以基于此构建哪些技能”“根据会话提出技能”“我用了哪些工作流”“我在此会话中做了什么”“从我的工作中提取模式”“将此会话转化为一项技能”“有哪些内容可以自动化”。如果用户提及会话 ID 或询问子 Agent 的活动，则由此技能处理。

先决条件

• 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

此操作分两个阶段进行：

1. 确定性导入（不使用 LLM）——提取尝试过的模型、成本事件、提示词更改、痛点片段、子 Agent 调用（带有描述、类型和提示词片段的 Agent 工具）、技能调用、工具序列（所有工具调用的有序列表）、工具使用频率和工作流模式（重复出现的多工具序列）。一份 50k-token 的转录内容会被压缩为精简的结构化 JSON 数据包。
2. 单次 LLM 调用——仅基于该精简数据包，提出部分 DesignJSON 补丁，其中包含一个 rationale 映射，用于说明哪些信号支撑了各字段，并提出技能方案——根据观察到的工作流模式和 Agent 编排推导出的潜在新技能。

数据包包含以下结构化信号：

• agents — 子 Agent 调用，包含 description、subagent_type 和 prompt_snippet
• skills — 会话中观察到的技能调用
• tool_sequence — 所有工具调用及其描述的有序列表
• tool_frequency — 每个工具的使用频率
• workflow_patterns — 重复出现的工具序列（例如，“Read → Edit → Bash”出现 3 次，可能表示一个测试修复循环）

不会自动应用提案。 请将提案（连同理由和任何技能方案）展示给用户并征求批准。提供以下选项：approve as-is、edit inline、discard and start fresh、approve partial（保留部分字段，重新访谈其他字段）。

如果提案包含 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 补丁。 输出一个 JSON 对象，仅包含回答涉及的 DesignJSON 字段。只能使用以下架构中的字段，不得臆造字段或值。如果回答与架构无关，则输出 {}。

补丁示例：

{"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_PROVIDER=anthropic 切换（默认值为 openrouter）。