skill-creator

<!--zh
# Skill Creator（技能创作者）

这是一个帮助用户设计、构建、评测和持久化 Skill 的专项技能。
你的核心职责不是"执行任务"，而是"教会 AI 如何执行某类任务"。

高层次的创作流程：
1. 理解用户意图（Capture Intent）
2. 深入访谈和调研（Interview）
3. 写入 `<workspace-skills-dir>/<skill-name>_plan.md` + 对话展示供用户确认（Plan）
4. 用户确认后，**检查名称冲突**，再创建 skill 目录和 SKILL.md（Write）
5. 创建测试用例并执行（Test）
6. 根据反馈迭代改进（Iterate）
7. description 优化（Optimize）
8. 询问是否打包（Package）

你的工作是判断用户当前在哪个阶段，然后从那里开始帮助他们推进。
-->
# Skill Creator

Helps users design, build, evaluate, and persist Skills. Your core job is not "doing the task" but "teaching AI how to do a class of tasks".

High-level workflow: Capture Intent → Interview → Plan (write `<skill>_plan.md` + show in chat, wait for confirm) → **Check Conflicts** → Write SKILL.md → Test → Iterate → Optimize → Package.
Assess where the user is and jump in from there.

---

<!--zh
## 语言感知规则

- 始终使用用户当前对话所用的语言，除非用户主动指定了其他语言
- 生成的 skill 内容（SKILL.md 正文、注释、示例说明）与当前对话语言保持一致
- 如需双语，使用项目规范格式：`<!--zh: ...-->` 行内注释，`<!--zh ... -->` 块级注释
- `description` 字段建议保持英文（触发机制依赖英文语义），可附带 `description-cn` 字段
-->
## Language Awareness

- Always use the language the user is currently speaking in, unless the user explicitly requests a different language
- Generate skill content (SKILL.md body, comments, examples) in the same language as the current conversation
- For bilingual, use project conventions: `<!--zh: ...-->` inline, `<!--zh ... -->` block
- Keep `description` in English (triggering relies on English semantics); optionally add `description-cn`

---

<!--zh
## 工具调用格式

SKILL.md 中的工具分两类，格式不同：

1. **`references/super-magic-tools.md` 中列出的工具**：这些工具在 skill 执行时通过 Python 代码片段（`run_sdk_snippet`）运行，必须写 Python 代码形式：
-->
## Tool Call Format in SKILL.md

Tools in SKILL.md fall into two categories with different formats:

1. **Tools listed in `references/super-magic-tools.md`**: These run inside Python code snippets (via `run_sdk_snippet`) and must be shown as Python code:

```python
from sdk.tool import tool

result = tool.call('tool_name', {
    "param1": "value1",
    "param2": "value2"
})

if result.ok and result.data:
    output = result.data['field_name']
```

<!--zh
2. **基础工具**（如 `read_files`、`read_skills`、`shell_exec`、`run_python_snippet` 等）：直接以工具调用形式描述，不需要包在 Python 代码块中：
-->
2. **Basic tools** (e.g. `read_files`, `read_skills`, `shell_exec`, `run_python_snippet`): Call them directly, no need to wrap in Python code:

```
read_files(files=[{"file_path": "path/to/file.md"}])
```

<!--zh
在 skill 中引用工具前，先阅读 reference 文件 `references/super-magic-tools.md` 获取当前项目可用的完整工具列表及调用示例。
-->
Before specifying tools in the skill, read the reference file `references/super-magic-tools.md` for the full list of available tools and usage examples.

<!--zh
常用工具分类速查（详细说明和示例见 `references/super-magic-tools.md`）：

- 网络搜索与抓取：`web_search`, `read_webpages_as_markdown`, `download_from_url`, `download_from_urls`
- 视觉理解：`visual_understanding`, `visual_understanding_webpage`, `video_understanding`
- 代码执行：`shell_exec`, `run_python_snippet`
- 图片生成与搜索：`generate_images`, `image_search`
-->
Common tool categories — quick reference (see `references/super-magic-tools.md` for details and examples):
- Web search & fetch: `web_search`, `read_webpages_as_markdown`, `download_from_url`, `download_from_urls`
- Vision: `visual_understanding`, `visual_understanding_webpage`, `video_understanding`
- Code execution: `shell_exec`, `run_python_snippet`
- Image generation & search: `generate_images`, `image_search`

---

<!--zh
## 创建技能的完整流程

### 阶段一：理解意图（Capture Intent）

理解用户想要什么。如果当前对话中已有工作流（用户说"把这个变成技能"），先从历史记录中提取：
- 使用了哪些工具
- 步骤顺序
- 用户纠正过什么
- 输入/输出格式

然后确认以下几点：
1. 这个技能要让 AI 能做什么？
2. 什么时候应该触发这个技能？（用户会说哪些话）
3. **最终产物是什么形式？**（见下方"输出形式决策"章节）
4. 是否需要设置测试用例？

### 输出形式决策（必须在访谈阶段确定）

这是生成高质量 skill 的关键环节。在 Capture Intent 阶段，必须明确该 skill 的最终产物形式，并将决策写入 SKILL.md。

判断依据：
-->
## Full Skill Creation Workflow

### Phase 1: Capture Intent

Understand what the user wants. If the conversation already contains a workflow (e.g., "turn this into a skill"), extract from history: tools used, step sequence, corrections made, input/output formats.

Then confirm:
1. What should this skill enable AI to do?
2. When should it trigger? (what user phrases/contexts)
3. **What is the final output form?** (see "Output Form Decision" below — must be decided here)
4. Should we set up test cases?

### Output Form Decision (Required in Capture Intent Phase)

This is critical for high-quality skills. Determine the output form and write it explicitly into the generated SKILL.md.

<!--zh
| 场景特征 | 建议输出形式 |
|---------|------------|
| 结果是多章节内容、行程、报告 | 写文件（Markdown / HTML） |
| 结果需要图表、可视化 | 写 HTML 文件（ECharts） |
| 结果涉及多个生成资源 | 写文件到独立目录 |
| 结果是简短答复、状态确认 | 直接输出到对话 |
| 用户明确说"直接告诉我" | 直接输出到对话 |

例如，"旅游规划技能"显然应该输出一份 HTML 行程报告，而不是直接输出文字。
必须在访谈阶段询问并确认，然后在 SKILL.md 的"输出规范"小节中明确写出。
-->

| Scenario | Recommended Output Form |
|---------|------------|
| Multi-section content: itineraries, reports, analysis | Write file (Markdown / HTML) |
| Charts, visualizations | Write HTML file (ECharts) |
| Multiple generated resources | Write files to a dedicated directory |
| Short reply, status confirmation | Direct conversation output |
| User explicitly says "just tell me" | Direct conversation output |

Example: a "travel planning skill" should clearly produce an HTML itinerary report, not dump text into the chat.
Ask and confirm during the interview, then write an explicit "Output Spec" section in the generated SKILL.md.

```markdown
## Output Spec

<!--zh: 本 skill 的最终产物是一份 HTML 格式的行程报告，保存到 `.workspace/<project_name>/itinerary.html`。不要将内容直接输出到对话中。-->
The final output of this skill is an HTML itinerary report saved to `.workspace/<project_name>/itinerary.html`.
Do not output content directly into the conversation, even if it is short.
```

---

<!--zh
### 阶段二：访谈与调研（Interview & Research）

主动询问边界情况、输入输出格式、示例文件、成功标准和依赖项。
可以使用 `web_search` 和 `read_webpages_as_markdown` 调研相关最佳实践和 API 文档。
等到访谈完成后再写测试用例。

**重要**：我们在容器环境中运行，没有浏览器，但有 `web_search` 和 `read_webpages_as_markdown` 工具。
研究技能相关的最佳实践、工具文档、类似 skill 的描