Guide · Agent skill
How to use the Brainstorming Before Building agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The brainstorming agent skill makes an AI coding agent design a change with you before it writes any code. It applies to features, behavior changes and bug fixes, and it is aimed at developers whose projects keep spec documents. After reading this guide you will know how to install the skill, how to ask for it, what the agent will do during the interview, and what the skill does and does not need to run.
Brainstorming Before BuildingJetBrains/thinkrail · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in the project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 3Set up the prerequisites. Make sure the spec-graph skill with its spec_create tool and the companion skills are available, and that the repository has a .thinkrail directory.
- 4Describe a change in plain words. Ask for a feature, behavior change or bug fix without a special command. The agent will apply the workflow.
- 5Answer the interview. Respond to the product questions first, then the technical questions. The agent records answers in the task-spec.
- 6Approve the design. Review the Design section the agent writes into the task-spec and accept it before the agent builds.
- 7Check the spec updates. After the build, review the spec amendments the agent makes in the Changes review.
What the brainstorming skill makes the agent do
Once installed, the agent stops jumping straight into code when you ask for a feature, a behavior change or a bug fix. It first finds the specs that govern the area, then interviews you in two phases. The product phase asks what the change is for, who it is for, what the user will see and do (including empty, error and edge states), and how you will know it is done. The technical phase covers constraints, compatibility, how the change will be verified, and any alternative approaches with their trade-offs.
The agreed design is recorded in a temporary task-spec file at .thinkrail/context/TASK-<slug>.md. The agent only builds after you accept the design. Afterwards it updates the project's durable specs to match what was built.
What the skill does not cover
The skill is meant for changes that alter behavior. It explicitly excludes questions, checks, and edits that change no behavior, such as typos, documentation or configuration changes, and mechanical refactors. For those tasks the agent will not run this workflow.
Install the brainstorming skill
Download the ZIP from this page and unzip it. You can install the skill in one of two places. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your repository
- Claude apps: Settings → Capabilities → Skills (upload)
Set up the prerequisites
The workflow depends on other pieces that are not included in these files. You need the spec-graph skill and its spec_create tool, which the workflow references. You also need the companion skills asking-user-questions and shipping-a-pr, and the amending-specs.md and fixing-a-bug.md files, which are in this skill folder.
Your repository also needs a .thinkrail directory, because that is where task-spec files are written. The skill file alone does not provide the .thinkrail folder or the spec-graph setup.
- spec-graph skill and spec_create tool (not included here)
- asking-user-questions and shipping-a-pr companion skills (not included here)
- amending-specs.md and fixing-a-bug.md (included in the skill folder)
- A repository with a .thinkrail directory
Trigger the skill with natural requests
You do not need a special command. Describe the change in plain words, and the agent will apply the workflow when the request is a feature, behavior change or bug fix. The skill's own description says to use it before implementing such changes, however small.
If the request already contains an explicit design or acceptance criteria, the agent treats that as approval of what they cover and builds on them without re-asking. Skipped questions do not block the work; the agent records its best assumption in the task-spec as unconfirmed and continues.
- Add a CSV export button to the orders page, with an empty state when there are no orders.
- Change the password reset link so it expires after 30 minutes.
- Users report the totals on the invoice page are wrong when a discount is applied. Fix it.
Example of a bug report
When a request reports something that behaves wrongly, the agent follows the bug branch in fixing-a-bug.md. It pins down the symptom, the expected behavior and how to trigger the problem, then tries to reproduce it when a safe command can show it. The agreed intended behavior is recorded in the task-spec's Bug section before any code changes. If the report turns out to be a feature request, the agent returns to the product phase.
- Symptom: what happens
- Expected behavior: what should happen instead
- Trigger: how to reproduce it
- Reproduce with a failing test where possible; never with a destructive command
Finish with the spec updates
After the change is built and verified, the agent follows amending-specs.md. It finds which durable specs the change affects, such as the goal doc, architecture.md, or the owning module's SPEC.md, and amends them so the specs match the code. You can review these edits in the Changes review. If you want to open a pull request afterwards, that work moves to the separate shipping-a-pr skill.
Safety notes: scripts and network
The skill runs no scripts and uses no network access. It is a set of written instructions that point to other skills and to a spec-graph workflow. The bug branch says never to run a destructive command to reproduce a bug. Because the skill only shapes how the agent works, the actions it takes come from the agent and the other skills it calls.
- Runs scripts: no
- Uses network: no
- Reproduction must never use a destructive command
Tips for better results
Answer the product questions in plain terms, since the agent records your answers in the task-spec. Ask the agent to show the design before it builds; the workflow expects you to approve it. For tiny changes, expect one short round and a few lines of task-spec rather than a long interview. If a change is really a typo or config edit, use the agent without this workflow, because the skill excludes those tasks.
- Answer product questions concretely, including error and empty states.
- Check the Design section in the task-spec before approving.
- Bundle independent decisions as separate requests; the agent will split them.
- Use it for small changes too; it scales down but does not switch off.
What people use it for
- Designing a new feature, such as a CSV export, with empty and error states agreed up front.
- Turning a vague bug report into a pinned symptom and expected behavior before any code changes.
- Recording why a behavior change was made in a task-spec and the durable specs for later teammates.
- Catching ambiguous requirements in a request before the agent writes code for it.
Frequently asked questions
How do I install the brainstorming agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
What does the brainstorming skill require to work?
It needs the spec-graph skill and its spec_create tool, the asking-user-questions and shipping-a-pr companion skills, and a repository with a .thinkrail directory. The spec-graph skill and companion skills are not included in these files.
Is the brainstorming skill free to use?
The source material does not state pricing or licence terms beyond the licence listed for the item, which is Apache-2.0. Check the repository's licence file for the full terms.
Does the brainstorming skill run code or use the network?
No. The skill runs no scripts and uses no network access. It is a set of written instructions that point to other skills and to a spec-graph workflow.
Why won't the agent start coding right away?
The skill deliberately delays implementation until the design is accepted. An explicit design or acceptance criteria in your request count as approval for what they cover, so the agent builds on those without re-asking.
Can I skip the brainstorming skill for small edits?
Yes. The skill excludes questions, checks, and edits that change no behavior, such as typos, documentation, configuration, or mechanical refactors. For small behavior changes it still runs, but with one short round and a few lines of task-spec.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you work in a codebase with spec documents and want the agent to design and get approval before coding, or if your team needs a traceable record of why changes were made. Pick something else if you want the agent to act immediately, if you mostly make tiny edits such as typos or config changes, or if your project has no spec-graph setup and no .thinkrail folder.
Download the skill