pneuma-skills: Skill for Claude Code

Create Mode

A guided journey for adding a new mode to Pneuma Skills. The journey has three phases — Discovery (ask the right questions), Brief (write down every key choice with rationale and get the user's confirmation), Implementation (generate files). Each phase has a clear handoff to the next; never skip Brief. Pneuma already has twelve modes and a stable contract layer; the cost of a thoughtful 10-minute design brief is much smaller than the cost of building the wrong viewer.

The reference material in references/ is where the knowledge lives — go read the relevant one whenever you're about to make a meaningful decision. SKILL.md is the journey, not the textbook.

---

When to use

Trigger this skill when the user asks for any of:

• "create a new mode for X"
• "fork slide / webcraft / … for a different domain"
• "scaffold a mode"
• "add a [mindmap | spreadsheet | timeline | annotator | …] mode"
• "design the viewer for a mode that …"

If the user only asks about an existing mode's behavior, this skill is not the right tool — direct them to docs/reference/viewer-agent-protocol.md or the mode's own SKILL.md.

---

Phase 1 — Discovery interview

Goal: extract enough signal that you can fill every field of the design brief without further interrogation. Ask one question at a time with AskUserQuestion; let each answer shape the next. Don't dump a 20-question survey on the user.

Discovery questions (ask in this order, branch as noted)

1. Identity — name (kebab-case), one-line displayName, two-line description, intended icon style. This is the only question you can pose as a single multi-line form.
2. Domain in one sentence — what is the user creating with this mode? A document? A canvas of objects? A timeline? Let the user answer free-form before you offer Source-kind options. Read references/domain-and-sources.md while they think.
3. Inspiration vs original — does this mode borrow content (commands, references, design language, taxonomy) from an existing tool, library, or project? If yes, ask the upstream's name + URL + license. This determines whether you'll write NOTICE.md and set inspiredBy. Read references/external-integrations.md for the borrow-vs-inspiration line.
4. Source kind (branch on Q2 + Q3) — present file-glob / json-file / aggregate-file / memory with the one that fits Q2's domain pre-selected as "Recommended". Explain why it fits in the option's description. If aggregate-file wins, note that you'll also generate domain.ts.
5. Workspace model (when Q4 is not memory) — "all" / "manifest" / "single"; do users author many independent files, an ordered/structured set, or one main document? See references/viewer-contract-patterns.md for the FileWorkspaceModel matrix.
6. ViewerAddress vocabulary — "what's the smallest thing the user can point at?" Propose a draft { contentSet?, ... } based on Q2's domain noun (slide / page / row / node / heading). Confirm with the user; explicitly name the coarse "where" key and any fine "within" key. See references/viewer-contract-patterns.md::ViewerAddress.
7. Initial action space — propose 2–5 actions with id / label / category / agentInvocable. Almost every viewer needs a navigate-to (navigate); add ui and custom only if the user names a concrete need. Don't list capture — it's framework-built-in.
8. External integrations (conditional — only ask if Q2 or Q3 implied an external API / SDK / CDN / library / API key) — does the viewer fetch external APIs (→ proxy)? does the agent or viewer need API keys (→ init.params with sensitive: true + envMapping)? does this need an MCP server (→ skill.mcpServers)? Read references/external-integrations.md for the proxy / Babel-JIT / NOTICE patterns.
9. Cloud surfaces — ask this every time, never conditionally; it's cheap now and expensive to retrofit. Two independent questions, in this order: (a) should a finished piece of work in this mode be shareable as a read-only page a stranger can open with no Pneuma installed? — that's the hosted player, and it obligates the viewer to render from workspace files alone, with no live backend; (b) does the mode produce a deployable static site? — that's Vercel / Cloudflare Pages deploy. Put the real trade-off in each option's description: "yes" buys shareability and costs a read-only degradation path plus a browser verification pass on every viewer change; "no" costs nothing and can be revisited in a later release. Read references/cloud-surfaces.md before you ask — the compatibility checklist there is what "yes" actually commits to.
10. Seed strategy — single file, multiple use-case content sets, or language×theme matrix? What's the first seed's narrative — what story does it tell to a brand-new user? See references/seed-and-showcase.md.
11. Evolution directive — give the evolve agent a one-sentence "what should it learn for this mode?" (e.g., "Learn the user's slide design preferences: typography, palette, density, structure"). This is what makes the mode personalize over time.