Skill Builder (UI/TUI): adopt conversational interview + convergence architecture and structured-JSON output

[initializ-mk]

Summary

Adopt a conversational interview + convergence architecture (and structured-JSON output) in the Forge UI/TUI Skill Builder, aligning it with the interview-style skill builder being built on the platform so the two don't drift.

Current state

The UI Skill Builder is already multi-turn — handleSkillBuilderChat passes the full req.Messages history to the LLM with skillBuilderSystemPrompt(mode, existing) (forge-ui/handlers_skill_builder.go:185, forge-ui/skill_builder_context.go). So the chat plumbing exists. What's missing is in the prompt:

1. No convergence discipline. skillBuilderPromptBase says "ask clarifying questions about requirements, security, and integration" but sets no ceiling — nothing stops it from over-asking, asking multiple questions at once, or re-asking something already answered. A stuck/looping interview is the main UX failure mode for a chat builder.
2. Fragile output format. It emits the SKILL.md (and scripts) inside nested quadruple-backtick fences (````skill.md). LLMs frequently mis-nest these, and the UI has to parse them out. A structured JSON envelope ({message, skill}) is far more robust to consume.
3. No custom-binary install recipes. The prompt can declare requires.bins but has no way to describe how to install a binary the base image lacks (apt/apk package, or download URL + dest + chmod).

The platform builder adds exactly these three (converge-quickly rules, a {message, skill} JSON shape, bins with install recipes). We should bring them into the Forge UI builder too.

Proposal

• Convergence rules in the prompt: read the whole conversation before replying; never re-ask an answered question; ask at most one blocking question per turn; the moment task + credential + tool are known, stop asking and return the full skill; prefer a sensible default (noted in the description) over a question.
• Structured output: return { "message": "<question or summary>", "skill": null | {…} } instead of markdown fences. skill: null while still interviewing; the full object once draftable. The UI renders message as chat and skill as the editor preview.
• Custom-binary install recipes in the bins field: {name} for a base-image/auto-installed tool, or {name, apt} / {name, url, dest, chmod} for a custom one.

Keep the Forge-correctness rules the platform prompt is missing

When porting the interview architecture, do NOT drop the Forge-runtime rules the current TUI prompt already gets right (the platform draft omits several of these — see review notes):

• Scripts receive tool-call args as JSON in $1 (INPUT="${1:-}"), never stdin/flags/cat.
• Scripts emit structured JSON, never raw text.
• ## Tool: sections with an Input parameter table, Output JSON schema, and several "user request → tool input" examples + detection heuristics — this is what the agent selects and shapes args on. If moving to a JSON shape, capture per-tool {name, input[], output, examples[]} so the compiled SKILL.md still has real ## Tool: sections.
• Tool→script mapping is _→- (my_search → scripts/my-search.sh); only .sh scripts register today (Python must be a .sh calling python3, with python3 in bins — until Skill-relative file resolution: read referenced markdown and execute referenced scripts (sh/py/js) from a skill's own directory #251).
• denied_tools, timeout_hint, ## Safety Constraints for mutating skills, and set -euo pipefail for bash.
• Edit mode must still preserve ## Tool: names exactly (breaking a wired agent otherwise — issue ui(skill-builder): allow editing and iterating on custom skills after creation #193).

Shared spec to avoid drift

Since the platform and the Forge UI builder now target the same SKILL.md contract, consider a single source-of-truth prompt/spec (or a shared skill JSON schema) consumed by both, so a change to the SKILL.md format updates both builders at once rather than diverging.

Acceptance criteria

• UI builder prompt enforces the convergence rules (one-question-max, no re-asking, draft-when-sufficient) — verified with a multi-turn test that it drafts without looping.
• Output is a structured {message, skill} envelope; the handler/UI consumes it instead of fence-parsing.
• bins supports custom install recipes (apt / url+dest+chmod).
• Per-tool {input, output, examples} captured so compiled ## Tool: sections are complete.
• All existing Forge-correctness rules retained ($1 input, JSON output, .sh/python-via-bash, denied_tools, safety, edit-mode tool-name preservation).
• Docs updated (docs/ui/skill-builder-llm.md).

Context

• Prompt + composition: forge-ui/skill_builder_context.go (skillBuilderPromptBase, skillBuilderSystemPrompt)
• Chat handler (already multi-turn): forge-ui/handlers_skill_builder.go
• Related: ui(skill-builder): allow editing and iterating on custom skills after creation #193 (edit mode), fix(skills): align skill catalog names with read_skill resolution #250 (skill-name ↔ read_skill resolution + directory listing), Skill-relative file resolution: read referenced markdown and execute referenced scripts (sh/py/js) from a skill's own directory #251 (skill-relative multi-language execution)

[initializ-mk]

Concrete motivation: #253 fixes a bug where a generated skill silently failed to populate the preview / be saved because extractArtifacts required an exact quadruple-backtick skill.md fence and the LLM's fence format varied (three backticks, language tags, trailing whitespace, etc.). #253 makes the parser tolerant as an immediate fix — but the durable fix is exactly this issue: a structured {message, skill} JSON envelope eliminates fence-parsing entirely, so this class of bug can't recur.

[initializ-mk]

#258 lands part 1: the interview/convergence architecture + custom-binary install recipes, with the Forge-correctness rules retained and now guarded by tests. Done in that PR:

• Convergence rules (one-question-max, no re-asking, draft-when-sufficient) — pinned by test
• bins custom install recipes (apt / apk / url+dest+chmod / run)
• Forge-correctness rules retained ($1 input, JSON output, .sh/python-via-bins, safety, edit-mode tool-name preservation) — pinned by test
• Docs (docs/ui/skill-builder-llm.md)

Remaining (part 2 — tracked here): the structured {message, skill} JSON output envelope + per-tool {input, output, examples} capture. That's a larger change — SSE streaming format, the handler (replacing extractArtifacts), a JSON→SKILL.md compiler that emits the ## Tool: sections, and the frontend consumer. It is de-risked, not blocked, by #253 (tolerant fenced-artifact extraction), so the current flow is robust in the meantime. Keeping this issue open for part 2.