# What Is the Brainstorming Skill Pattern and How to Create One in OpenAI Plugins > Learn the brainstorming skill pattern in OpenAI plugins. Enforce a nine-step checklist before code generation using this reusable design-time workflow. Master plugin development today. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-23 --- **The brainstorming skill pattern is a reusable design-time workflow defined in the `openai/plugins` repository that enforces a strict nine-step checklist—culminating in a mandatory transition to the `writing-plans` skill—before any code generation can occur.** The brainstorming skill pattern serves as the foundation of the Superpowers plugin collection, providing a state-machine-driven framework that guides AI agents through structured architectural planning. According to the source code in [`plugins/superpowers/skills/brainstorming/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/SKILL.md), this pattern ensures that every implementation phase is preceded by comprehensive context exploration, approach evaluation, and documented design approval. ## What Is the Brainstorming Skill Pattern? ### Core Definition and Design-Time Purpose The brainstorming skill pattern is a **design-time** constraint mechanism that prevents premature code generation by mandating a specific sequence of analytical steps. Located at [`plugins/superpowers/skills/brainstorming/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/SKILL.md), the canonical definition includes a YAML front-matter block declaring the skill name, followed by a strict checklist that agents must execute in order. The pattern functions as a hard gate: no implementation skill may be invoked until the brainstorming workflow reaches its terminal state, which explicitly calls the `writing-plans` skill. ### The Nine-Step Checklist The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file enumerates nine ordered tasks that constitute the complete brainstorming workflow: - **Explore project context** – Analyze relevant files and recent commits to establish situational awareness. - **Offer visual companion** – Optionally propose a browser-based mockup tool when visual reasoning is required. - **Ask clarifying questions** – Elicit requirements through sequential, one-at-a-time questioning. - **Propose 2-3 approaches** – Present alternative solutions with explicit trade-off analysis. - **Present design** – Deliver architecture in sections, securing user approval after each segment. - **Write design doc** – Generate a formal specification document. - **Spec self-review** – Internally validate the document for completeness and fix placeholders inline. - **User reviews spec** – Incorporate feedback through a structured review cycle. - **Transition to implementation** – Invoke the `writing-plans` skill to proceed to code generation. ## Architecture and Key Files The brainstorming pattern relies on four primary components that work together to provide workflow orchestration, optional UI support, and plugin system registration. ### SKILL.md – Core Workflow Definition The file [`plugins/superpowers/skills/brainstorming/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/SKILL.md) contains the authoritative specification. It defines the skill name in YAML front matter (`name: brainstorming`), provides the nine-step checklist, and embeds a GraphViz dot diagram that models the state machine transitions. This file also specifies hard gates that prevent state advancement until explicit user approval is recorded. ### visual-companion.md – Optional UI Support When the workflow detects visual questions, the skill can spawn a companion server documented in [`plugins/superpowers/skills/brainstorming/visual-companion.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/visual-companion.md). This component creates a persistent session directory at `./.superpowers/brainstorm/` that survives agent restarts, or falls back to a temporary `/tmp` location when no project directory is specified. ### plugin.json – System Registration The skill must be registered in [`plugins/superpowers/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/superpowers/.codex-plugin/plugin.json) to enable discovery by the agent runtime. The registration appears under the `longDescription` array, listing `brainstorming` as an available capability that agents can invoke via the `call: brainstorming` directive. ### README.md – Documentation Entry High-level documentation in [`plugins/superpowers/README.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/README.md) categorizes brainstorming as a core Superpowers capability, describing its role as the mandatory precursor to all implementation activities. ## The Brainstorming Workflow State Machine The SKILL file embeds a GraphViz diagram that visualizes the strict process flow, including decision points that govern the visual companion offer and design approval loops: ```dot digraph brainstorming { "Explore project context" -> "Visual questions ahead?"; "Visual questions ahead?" -> "Offer Visual Companion" [label="yes"]; "Visual questions ahead?" -> "Ask clarifying questions" [label="no"]; "Offer Visual Companion" -> "Ask clarifying questions"; "Ask clarifying questions" -> "Propose 2-3 approaches"; "Propose 2-3 approaches" -> "Present design sections"; "Present design sections" -> "User approves design?"; "User approves design?" -> "Write design doc" [label="yes"]; "User approves design?" -> "Present design sections" [label="no, revise"]; "Write design doc" -> "Spec self-review (fix inline)"; "Spec self-review (fix inline)" -> "User reviews spec?"; "User reviews spec?" -> "Write design doc" [label="changes requested"]; "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"]; } ``` The diagram enforces two critical hard gates: the workflow cannot proceed to document writing without design approval, and cannot transition to implementation without spec approval. The terminal node explicitly invokes the `writing-plans` skill, ensuring that code generation only occurs after complete design documentation. ## How to Create a New Brainstorming-Style Skill To implement a custom skill that follows this disciplined design-first approach, replicate the canonical structure and adapt the checklist to your domain-specific requirements. ### 1. Create the Skill Directory Structure Establish a namespace for your skill under `plugins//skills//`. This directory will contain all workflow definitions and auxiliary assets. ### 2. Define SKILL.md with Workflow Constraints Create a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file containing: - YAML front matter with `name: ` - A concise `description` identifying the skill as design-time - A numbered **Checklist** enumerating ordered tasks - (Optional) A **GraphViz dot** diagram modeling state transitions - **Hard gates** using `…` tags to enforce completion checkpoints ### 3. Register in plugin.json Add the skill name to the capabilities array in `plugins//.codex-plugin/plugin.json` to enable agent discovery and invocation. ### 4. Add Auxiliary Assets (Optional) Include companion files such as [`visual-companion.md`](https://github.com/openai/plugins/blob/main/visual-companion.md) and server scripts if your workflow requires specialized UI tooling or external visual reasoning support. ### 5. Document Output Conventions Specify in your README or documentation where design artifacts are stored—for example, `docs/superpowers/specs/`—and clarify the conditions that trigger transition to implementation skills. ### Minimal Example Skeleton ```markdown --- name: my-brainstorm-skill description: "Guides the user through a structured design discussion before any code is written." --- # My Brainstorm Skill ## Checklist 1. **Explore project context** – list relevant files, recent commits. 2. **Offer visual companion** – (optional) propose a browser-based mockup tool. 3. **Ask clarifying questions** – one-at-a-time. 4. **Propose 2-3 approaches** – with trade-offs. 5. **Present design** – in sections, ask for approval after each. 6. **Write design doc** – store under `docs/...`. 7. **Spec self-review** – fix placeholders. 8. **User reviews spec** – incorporate feedback. 9. **Transition to implementation** – invoke `writing-plans`. ## State Diagram ```dot digraph my_brainstorm { "Explore project context" -> "Visual questions ahead?"; "Visual questions ahead?" -> "Offer Visual Companion" [label="yes"]; "Visual questions ahead?" -> "Ask clarifying questions" [label="no"]; "Offer Visual Companion" -> "Ask clarifying questions"; "Ask clarifying questions" -> "Propose 2-3 approaches"; "Propose 2-3 approaches" -> "Present design"; "Present design" -> "User approves design?"; "User approves design?" -> "Write design doc" [label="yes"]; "User approves design?" -> "Present design" [label="no, revise"]; "Write design doc" -> "Spec self-review"; "Spec self-review" -> "User reviews spec?"; "User reviews spec?" -> "Write design doc" [label="changes requested"]; "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"]; } ``` ``` Place this file at `plugins//skills/my-brainstorm-skill/SKILL.md`. ## Practical Implementation Examples ### Invoking the Skill from an Agent Definition ```yaml # plugins/myplugin/skills/my-brainstorm-skill/agents/openai.yaml name: my-brainstorm-skill description: "Runs the brainstorming workflow before any code generation." steps: - call: brainstorming # Delegates to the core brainstorming skill - call: writing-plans # Only runs after successful approval ``` The `call: brainstorming` directive instructs the agent runtime to execute the standardized workflow defined in [`plugins/superpowers/skills/brainstorming/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/SKILL.md). ### Writing the Design Document Within the skill implementation, step six persists the design specification using this path convention: ```yaml write_file: path: docs/superpowers/specs/{{date}}-{{topic}}-design.md content: | # Design Specification ## Overview {{generated_overview}} ## Architecture {{generated_architecture}} ``` This operation creates a markdown file under `docs/superpowers/specs/` that serves as the authoritative blueprint for subsequent implementation phases. ### Launching the Visual Companion Server When visual reasoning is required, the skill spawns a companion server that manages session persistence: ```bash # scripts/start-server.sh (excerpt) if [ -n "$PROJECT_DIR" ]; then SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}" else SESSION_DIR="/tmp/brainstorm-${SESSION_ID}" fi node server.cjs --session-dir "$SESSION_DIR" ``` The script checks for a project directory to determine persistence: if `PROJECT_DIR` exists, the session survives restarts at `./.superpowers/brainstorm/`; otherwise, it utilizes a temporary `/tmp` location cleaned up on exit. ## Summary - The brainstorming skill pattern enforces a **nine-step design workflow** that must complete before any code generation occurs. - The canonical definition resides in [`plugins/superpowers/skills/brainstorming/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/brainstorming/SKILL.md), which includes YAML metadata, a strict checklist, and a GraphViz state machine diagram. - **Hard gates** prevent progression to implementation until the user explicitly approves both the design sections and the final specification document. - The workflow always terminates by invoking the `writing-plans` skill, creating a formal handoff between design and implementation phases. - Custom skills follow the same directory structure, registration mechanism in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json), and optionally include visual companion tooling for UI-intensive design tasks. ## Frequently Asked Questions ### What triggers the visual companion during a brainstorming session? The visual companion is offered when the workflow reaches the "Visual questions ahead?" decision node in the state machine. If the user confirms the need for visual reasoning—such as mockups or diagrams—the skill launches a browser-based server documented in [`visual-companion.md`](https://github.com/openai/plugins/blob/main/visual-companion.md) rather than proceeding directly to clarifying questions. ### Where does the brainstorming skill store generated design documents? According to the SKILL specification, step six ("Write design doc") must create markdown files under `docs/superpowers/specs/` using the naming convention `{{date}}-{{topic}}-design.md`. This path is hard-coded in the skill implementation to ensure consistent artifact location across all Superpowers plugin sessions. ### How does the skill prevent implementation from starting before design approval? The workflow implements **hard gates** at two critical points: the transition from design presentation to document writing requires "User approves design?", and the transition to implementation requires "User reviews spec?". Additionally, the terminal node explicitly invokes `writing-plans` rather than any implementation skill, ensuring code generation cannot precede documented design approval. ### Can I customize the checklist steps in a custom brainstorming skill? Yes. When creating a new skill under `plugins//skills//SKILL.md`, you can adapt the nine-step checklist to your domain while maintaining the same structural requirements: YAML front matter with the skill name, ordered task enumeration, optional GraphViz state diagrams, and hard gate tags to enforce completion checkpoints before transitioning to subsequent skills.