waggle-os/docs/ux-refactor/gap-cards/S19-skill-builder.md

Gap Card — S19 · Skill Builder

UX-refactor planning artifact. Execution model is LOCKED in-place incremental refactor of apps/web + targeted sidecar extensions. Mockups are directional (PRD §24); PRD acceptance criteria win. Every claim below is grounded in a cited file.

Sources: PRD §12.6 + §16.8 (docs/.../Waggle_OS_UX_Refactor_PRD.md), Blueprint Screen 19 (_blueprint_extracted.txt:417-421, state model :464), mockup Waggle_OS_Handoff_Assets/screens_18_21_builders_and_marketplace.png, backend-map sections/03d + 05g, inventories under docs/ux-refactor/_inventory/.

---

1. Screen & purpose

Skill Builder — the create/edit surface for a reusable capability (Skill). PRD §12.6: a stepper Builder ("Basic Info → Instructions → Inputs & Outputs → Tools & Data → Review & Create"), with test-run before publishing and assignment to agents/workspaces/automations or direct use. Blueprint Screen 19 (_blueprint_extracted.txt:417-421): "Create reusable capability. Define prompt, inputs/outputs, tools, memory access, test." States: Draft; test pass/fail; published; archived. Acceptance: "Skills are inspectable and reusable by agents/automations" (PRD §12.6 acceptance: "a user can understand what a skill does, where it is used, and what access it has").

This is the Builder half of the Intelligence layer's Skills surface (S06 Skills Hub is the browse/library half). PRD Roadmap puts both in Sprint 6 / Phase 3 (PRD:344-351, :236-240). The mockup tile labelled "Skill Builder" shows a left form column (name/description/category + instructions textarea) and a right column (tools picker + memory access + a Test panel + a primary "Create Skill" action) — directional confirmation of the §12.6 stepper.

---

2. Required states (PRD / Blueprint)

PRD §14.1 global states (every screen) + Blueprint Skills row (_blueprint_extracted.txt:464): Loading, empty, populated, error; Installed, draft, custom, workspace, marketplace, update available; recovery: Test, install, publish, archive, rollback.

Builder-specific lifecycle (Blueprint Screen 19 :417-421): Draft → test pass/fail → published → archived, with PRD global add-ons: validation error, approval required (skills that request elevated tool/secret access), offline/local-only.

Stepper steps the Builder must implement (PRD §12.6 :542):

1. Basic Info — name, description, category.
2. Instructions — the prompt/steps body.
3. Inputs & Outputs — declared input params + expected output shape.
4. Tools & Data — tools/data + memory access (read scope).
5. Review & Create — summary + Test run + publish-to-scope (personal/workspace/team).

Per-state behaviours required:

• Validation error — name normalises to kebab-case; empty name/description/steps blocked (backend already 400s on these — §5).
• Test pass/fail — inline Test panel showing the injected-prompt preview + parsed metadata.
• Published — confirmation + the new skill appears in the Hub (Installed list).
• Approval required — when declared tools include elevated/secret/code-exec permissions (frontmatter permissions block exists — skill-frontmatter.ts:40-48).

---

3. Current state in repo

Disposition: create-new (frontend Builder), keep-promote (backend structured-create contract). There is no Skill Builder component anywhere in apps/web/src — grep for SkillBuilder|Skill Builder|skill-builder over apps/web/src returns 0 matches. Skill creation today is only available to the agent (the create_skill tool, skill-creator.ts:8), not to the user via UI.

What exists today:

• apps/web/src/components/os/apps/CapabilitiesApp.tsx — "Skills & Apps". A browse/install/test surface only. Tabs: installed | starter | marketplace | tools | audit (:80, :358). It lists packs (PackCard :190), shows a detail drawer (PackDetail :249), installs (handleInstall/handleMarketplaceInstall :164,:174), and tests an existing skill (handleTestSkill → POST /api/skills/test :88-102). It has NO create/edit form. This is the natural host to add a "+ Create Skill" entry point that launches the new Builder.
• apps/web/src/lib/adapter.ts:652 — createSkill({ name, description }) exists but is lossy: it POSTs to /api/skills/create with only {name,description} (no steps/tools/category), while the backend requires a non-empty steps[] (skills.ts:434). So the one adapter method that targets the create route is under-specified and has no caller in apps/web/src (grep: createSkill appears only at its definition). Needs rework to the full template shape.
• apps/web/src/lib/types.ts:210 — SkillPack (id/name/description/category/skills[]/installed/trust). This is a pack/catalog shape, NOT a skill-authoring shape (no instructions/inputs/outputs/tools).
• packages/agent/src/skill-creator.ts:11 — SkillTemplate (name, description, triggerPatterns[], steps[], tools[], category) + generateSkillMarkdown() (:26). This is the canonical authored-skill model the backend writes from.
• packages/agent/src/skill-frontmatter.ts:53 — ParsedSkill/SkillFrontmatter (name, description, scope personal→workspace→team→enterprise :27, permissions block :40-48). This is the read/parse side; the Builder's "memory access / permissions" + "scope" map onto this.

Conclusion: backend authoring contract is solid and reusable; the frontend Builder UI is greenfield, and the adapter method must be widened to the full template.

---

4. Frontend work

Create (new):

• apps/web/src/components/os/overlays/SkillBuilder.tsx — a 5-step stepper modal/drawer. Place it in overlays/ (consistent with CreateWorkspaceDialog.tsx, SpawnAgentDialog.tsx). Reuse the DS Builder-stepper pattern (PRD §19.1 lists "Builder stepper" as a core component — none exists yet, so this is the first stepper; AgentBuilder S18 + AutomationBuilder S20 should share it — see §7).
  • Step 1 Basic Info: name, description, category (select from the SKILL_FAMILIES family set in skills.ts:13-31: writing/research/decision/planning/communication/code/creative — surface these as the category options, not the narrower SkillPack.category 5-union).
  • Step 2 Instructions: ordered steps[] editor (add/remove/reorder) + optional triggerPatterns[] (maps directly to SkillTemplate.steps/.triggerPatterns).
  • Step 3 Inputs & Outputs: inputs[] / outputs[] param rows. Backend does not persist these structured today (§5) — render them into the markdown body for v1, or block on the §5 backend extension.
  • Step 4 Tools & Data: tools[] multiselect (source the tool catalog already enumerated in CapabilitiesApp.tsx:422-434 — extract that hardcoded list to a shared module to avoid a third copy; the agent tool registry is packages/agent/src/tools.ts) + memory access / scope (SkillScope personal/workspace/team — skill-frontmatter.ts:27) + a permissions toggle group (skill-frontmatter.ts:40-48).
  • Step 5 Review & Create: summary card + Test button (calls existing test route) + Create.
• Optional apps/web/src/components/os/overlays/skill-builder/ substeps if the file exceeds ~400 LOC (CLAUDE.md file-org rule).

Rework:

• apps/web/src/lib/adapter.ts — widen createSkill (:652) to createSkill(t: { name; description; steps: string[]; tools?: string[]; category?: string; triggerPatterns?: string[] }) (full SkillTemplate shape, matching skills.ts:424-430). Add updateSkill(name, content) → PUT /api/skills/:name (skills.ts:506) for edit, and reuse the existing test call (CapabilitiesApp inlines fetch('/api/skills/test') :91 — promote it to an adapter.testSkill(skillName, testInput?) method so the Builder and CapabilitiesApp share one path).
• apps/web/src/components/os/apps/CapabilitiesApp.tsx — add a "+ Create Skill" button (header, next to the grid/list toggle :340) that dispatches waggle:open-app or opens the Builder overlay via useOverlayState (the overlay open/close registry — hooks/useOverlayState.ts, per frontend inventory §c). Optionally render an edit affordance on installed custom skills.

Wiring:

• Register the overlay in Desktop.tsx (overlays block) + add a flag to useOverlayState.
• Ctrl+K "Create → Skill" command should open it (PRD §12.3 Create category; GlobalSearch.tsx already loads skills :129).

Props/state: local stepper state object { step, name, description, category, steps[], triggerPatterns[], inputs[], outputs[], tools[], scope, permissions, testResult, status }. On Create → adapter.createSkill(template); on Test → adapter.testSkill(name). No new global store; optimistic insert into the Skills Hub list on success (CapabilitiesApp already refetches via getSkills).

---

5. Backend work (PRD §16.8)

PRD §16.8 endpoint	Status	Note / what to EXTEND vs NET-NEW	Substrate
GET /api/skills	EXISTS	skills.ts:164 — list installed skills. Hub/Builder list source.	~/.waggle/skills/*.md files
POST /api/skills	EXISTS	skills.ts:167 raw {name,content}; POST /api/skills/create (skills.ts:431) is the structured one the Builder should use ({name,description,steps[],tools?,category?} → generateSkillMarkdown + redactSkillContent + audit + hash).	skill files + auditStore + skillHashStore
PATCH /api/skills/:id	PARTIAL	Update is PUT /api/skills/:name keyed by name, method PUT, body {content} (skills.ts:506-510). PRD uses PATCH+:id. EXTEND: accept PATCH alias + name↔id mapping (skills have no numeric id — name is the id).	skill files
POST /api/skills/:id/test	PARTIAL	Test exists as POST /api/skills/test (body {skillName, testInput?}, skills.ts:570-575) — not a per-id path. EXTEND: add :id-path variant (or keep body-driven; Builder can call either). Returns injected-prompt preview + metadata.	skill files + starter dir
POST /api/skills/:id/install	PARTIAL	No unified per-skill install-by-id. Closest: POST /api/skills/starter-pack/:id (skills.ts:161), POST /api/skills/capability-packs/:id (:163), marketplace POST /api/marketplace/install (marketplace.ts, Tier: PRO, SecurityGate). EXTEND: add a dispatcher /skills/:id/install that routes by source — OR leave install to the Hub (S06) and have the Builder only create (create == installed, since authored skills write straight to ~/.waggle/skills/).	skill files / marketplace

Net-new backend gap surfaced by the PRD stepper (NOT in §16.8, but needed for §12.6 Step 3): the structured-create contract (SkillTemplate, skill-creator.ts:11) has no inputs/outputs and no memoryScopes fields. PRD §15 skill object (and Blueprint §551 "Skill … inputs, outputs, requiredTools, requiredMemoryScopes") expects them. Two options, both in-place:

• v1 (no migration, recommended): Builder serialises inputs/outputs/memory-scope into the markdown body via an extended generateSkillMarkdown (add optional inputs?/outputs?/scope? to SkillTemplate); they round-trip as ## Inputs / ## Outputs / frontmatter scope: sections. parseSkillFrontmatter already reads scope (skill-frontmatter.ts:27) and permissions.
• v2 (later): promote to structured frontmatter if inputs/outputs become a query/filter axis.

No .mind migration. Skills are filesystem markdown (~/.waggle/skills/*.md), not SQLite — confirmed skills.ts:46-49. The only DB touch is the install-audit record on create (skills.ts:476, writes to .mind install_audit) + the skill-hash store. The audit record() call already passes riskLevel:'low' so it sidesteps the latent risk_level CHECK drift noted in substrate-types §(d) — no new exposure.

Security: create/update already pass content through redactSkillContent() (strips secrets+user-paths, skills.ts:464,:521) and guard path-traversal in the name (:447). The Builder must NOT bypass these — always go through /api/skills/create / PUT /api/skills/:name, never write files another way. Elevated permissions (codeExecution/secrets/network) in a skill should trigger the §2 "approval required" UX (PRD §12.6 / §17.3 elevated-action approval) — currently no approval gate fires on skill authoring; flag as an open item (§9).

---

6. Shared types needed (PRD §15 vs lib/types.ts)

PRD §15.2 declares ExtensionType = 'skill' | ... — MISSING in apps/web/src/lib/types.ts (substrate-types §e). For S19 specifically:

• Add SkillTemplate (authoring) FE type mirroring packages/agent/src/skill-creator.ts:11 (currently the FE only has the catalog-shaped SkillPack types.ts:210). Fields: name, description, category, steps[], triggerPatterns[], tools[] + PRD additions inputs[], outputs[], scope (SkillScope), permissions. Keep SkillPack (catalog) distinct from SkillTemplate (authoring) — they are different objects.
• Reuse SkillScope (personal|workspace|team|enterprise) from skill-frontmatter.ts:27 rather than redeclaring (export it through the FE if needed; PRD §15.2 Scope is the broader personal/workspace/team/organization — reconcile: skills use the enterprise variant).
• SkillPack.category is a narrow 5-union (types.ts:213) that does not match the backend SKILL_FAMILIES 7-set (skills.ts:13). Widen the FE category union to the family set so the Builder category picker and the Hub badges agree.

---

7. Dependencies (screens/phases first)

• Phase/Sprint: PRD Sprint 6 / Phase 3 — Intelligence layer (PRD:344-351, :236-240).
• Hard prereq — DS Builder Stepper component (PRD §19.1). None exists. S19 is the cheapest place to introduce it, but S18 Agent Builder and S20 Automation Builder share the exact same stepper pattern — build the stepper as a reusable primitive (components/ui/ or components/os/overlays/builder-stepper/) so all three Builders consume it.
• Sibling — S06 Skills Hub (the browse/library half, hosted today by CapabilitiesApp.tsx). S19 launches from the Hub and writes into it (created skill → Installed list). They should ship together or S06 first.
• Soft — Command Center (Ctrl+K) (S03) for the "Create → Skill" entry (PRD §12.3); not blocking.
• Soft — Agent Builder (S18) / Automation Builder (S20) consume skills via skillIds (PRD §15.5) — they depend on skills existing, not on the Builder UI. Skill→agent assignment is a downstream wiring concern.

---

8. Effort: M

Backend is mostly EXISTS/PARTIAL (structured-create, test, update all present — only thin aliases PATCH/:id-path + an optional inputs/outputs/scope extension to generateSkillMarkdown, no DB migration). The frontend is a net-new 5-step stepper + adapter widening + a reusable stepper primitive shared with S18/S20 — real but bounded UI work. Not S (greenfield component + 3 endpoint extensions); not L (no new substrate, no migration, backend authoring path already proven via the create_skill tool).

---

9. Open questions

1. Install vs create semantics. Authored skills write straight to ~/.waggle/skills/ (create == installed). Does PRD POST /api/skills/:id/install (§16.8) apply to the Builder at all, or only to the Hub/Marketplace install flow? Recommend: Builder = create-only; install-by-id lives in S06.
2. Inputs/Outputs persistence. v1 markdown-body serialisation vs structured frontmatter — confirm whether inputs/outputs need to be queryable (drives the v1-vs-v2 backend choice in §5).
3. Approval gate on elevated skills. Should authoring a skill that declares permissions: {codeExecution|secrets|network} trigger the PRD §17.3 approval prompt at create time, or only at run time? No gate fires today on authoring.
4. Scope vocabulary reconciliation. SkillScope uses enterprise; PRD §15.2 Scope uses organization. Pick one for the Builder's publish-to-scope picker.
5. Test-run fidelity. POST /api/skills/test returns only the injected-prompt preview + parsed metadata (skills.ts:570), it does not execute the skill against an LLM. Is preview-only sufficient for the PRD "test pass/fail" state, or is a live dry-run expected? (Live run would be net-new and lean on /api/agent/run.)
6. Category source of truth. Reconcile SkillPack.category (5-union) vs SKILL_FAMILIES (7-set) vs SkillTemplate.category (free string) — which is canonical for the picker?