obra/superpowers · skills/brainstorming/SKILL.md
brainstorming
“A sharp 'find out what they want before you build' skill whose trigger fires on nearly everything”
What it does
Makes the agent pause before building. It reads the project, asks one question at a time, plays back what it heard, offers two or three approaches, and writes a design doc. Nothing gets built until the user approves it; then it hands off to a planning skill.
- When the agent uses it
- Before any creative work: new features, components, behavior changes, or plans, in software or outside it, such as a talk, a business or a renovation.
- Who it is for
- For superpowers users who want agents to clarify intent and get a design approved first; skip it if you want fast execution or don't use writing-plans.
- What it costs
- 254 lines, about 4.1k tokens once the agent loads it.
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).
What it tells the agent to do
- Judge whether the request is complete; if it is clear and small, just do it and say what you did
- Read the project and any spec, plan or files they referenced before asking anything
- First message: echo the request and what you found, ask one open question, and offer to just dive in
- Ask one question at a time and play back each understood part in 200-300 words
- Lay out two or three approaches in their own message, recommend one, and let them pick
- Size the work, write the design doc to docs/superpowers/specs/, and run a builder-check subagent for projects
- Get approval of the doc, then invoke superpowers:writing-plans and no other skill
Lines worth reading
Straight from the file, with why each one matters.
line 3You MUST use this before any creative work
The trigger. Aimed at almost every request; the body softens it by letting clear, small tasks skip straight to doing.
line 9that belief is usually thinner than it feels
A fair diagnosis of agents that confidently build the wrong thing.
line 290A default they never heard is one they couldn't reject.
The sharpest rule in the file. Defaults are fine, as long as you say them out loud.
line 182Agentic work is waterfall, but very, very
A surprising framing that justifies throwaway spikes as the cheap way to learn what they want.
line 289Options steer. Ask them to describe it first.
A counterintuitive rule: no multiple choice until you know the why.
Watch out for
- Medium
Starts a local server for the visual companion, set up in a file that couldn't be reviewed, so what it runs is unknown.
line 315read `visual-companion.md` in this directory before
- Low
Commits the design doc to the repo without saying to ask first.
line 246`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
- Low
The all-caps, catch-all trigger can pull the skill into requests that didn't need a conversation, adding friction.
line 3You MUST use this before any creative work
The scorecard
- TriggerSays when to use it6/10
Says when, loudly and too broadly; never says what it does (design doc, approval gate).
- FocusOne clear job7/10
One job, clarify then design, though the visual companion and spikes widen it.
- LeanLight to load6/10
About 4,100 tokens and under 500 lines, with some narration and repeated rules.
- ConcreteSteps you can follow7/10
Clear sequence, examples, a file path and a gate; no commands of its own.
- SafeSafe to run8/10
No destructive steps; an unseen server setup and an automatic commit are the catches.
What it does well
- Concrete examples of good questions, like the bakery site and mid-round voting, show the tone instead of describing it
- The HARD-GATE spells out exactly what counts as building and its two exceptions
- Sorting builder questions into answered, minor and theirs keeps follow-ups to one round
How it could be better
Say what it does in the description
The agent only sees the description, and it names a trigger but not the outcome, so it fires on everything without signaling its cost.
Adddescription: "Clarifies what the user wants before building: reads the project, asks one question at a time, proposes approaches, and writes a design doc for approval. Use when a request for a new feature, component, behavior change or plan leaves real choices open. Skip for small, fully specified edits."
Ask before committing the design doc
Committing to the user's repo is a visible change they may not expect from a brainstorming step.
Add**Where it goes:** in a software repo, `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`. Ask before committing it.
Describe the visual companion server inline
Readers of SKILL.md can't tell what the server runs or exposes without the linked file.
AddIf they accept, read `visual-companion.md` in this directory before starting the server. It runs <command> on <localhost:port>, serves only <what>, and stops with <command>.
Cut the opening narration
The first two paragraphs explain motivation the rules already carry, and they load every time.
Add# Brainstorming Find out what your human partner wants, and why, before anything gets built.
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.