skill-creator

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

---

## 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
- Default to single-language skill content. If the user explicitly requests multiple languages, write ordinary multilingual sections and do not use HTML comment annotations in SKILL.md.
- Keep `description` in English (triggering relies on English semantics)

---

## Tool Call Format in SKILL.md

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

1. **Tools listed in `references/system-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']
```

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"}])
```

Before specifying tools in the skill, read the reference file `references/system-tools.md` for the full list of available tools and usage examples.

Common tool categories — quick reference (see `references/system-tools.md` for details and examples):
- Web search & fetch: `web_search`, `read_webpages_as_markdown`; external file downloads use the `download` skill with `run_sdk_snippet`
- Vision: `visual_understanding`, `visual_understanding_webpage`, `video_understanding`
- Code execution: `shell_exec`, `run_python_snippet`
- Image generation & search: `generate_images`, `image_search`

---

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

| 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

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

---

### Phase 2: Interview & Research

Proactively ask about edge cases, input/output formats, example files, success criteria, dependencies.
Use `web_search` and `read_webpages_as_markdown` to research best practices and API docs.
Wait until the interview is done before writing test cases.

**Note**: This environment has no browser, but `web_search` and `read_webpages_as_markdown` are available.
Use them to research best practices, tool docs, and description patterns for similar skills.

---

### Phase 3: Output Plan Document

After the interview, write the plan to `<workspace-skills-dir>/<skill-name>_plan.md` (at the root of `<workspace-skills-dir>/`, not inside the skill subdirectory — this avoids pre-creating the skill directory). Also present the plan in chat for the user to read.

Plan document contents:
- Skill scope and boundaries (what it can/cannot do)
- Tool list with selection rationale (with code format examples)
- Expected SKILL.md structure outline
- Whether `scripts/`, `references/`, `assets/` subdirectories are needed
- Final output form (from Phase 1 decision)
- Evaluation plan (test prompts, expected outputs)

**Wait for user confirmation before proceeding to Phase 4.**

---

### Phase 4: Check Conflicts and Write Files

After user confirms the plan, **check for name conflicts first**, then create files.

**Conflict check** — look at the `<available_skills>` block already in the system prompt to see if a skill with the same name already exists. No tool call or shell command is needed for this step.

**Conflict rules:**
- Same name is a built-in skill (system level, `can_override: false`): **Cannot overwrite**.
  - Ask the user to pick a **new** name, re-confirm, then write to `skills/<new-name>/`.
- Same name already exists at `<workspace-skills-dir>/<name>/`: Ask user for confirmation.
  - If confirmed: delete the entire directory first, then recreate from scratch (do not edit in place).
- No conflict: proceed to write files directly.

**Writing SKILL.md:**

SKILL.md **must** start with YAML frontmatter — the packaging validator rejects files without it.

```markdown
---
name: skill_name
description: "One sentence on what this skill does. Use when [specific trigger conditions — what the user is trying to accomplish