Guide · Agent skill
How to use the Idea Refine agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Idea Refine is an agent skill that helps you turn a rough idea into a sharper, more testable concept. It works as an interactive conversation: the agent restates your idea, asks a few questions, proposes variations, and then tests the strongest directions for weak points. This guide explains what the skill does, how to install it, how to trigger it, and what to check before you run it.
Idea Refineaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download and unzip. Download the idea-refine ZIP from this page and unzip it so you have an idea-refine folder containing SKILL.md.
- 2Place or upload the skill. Copy the folder to ~/.claude/skills/ for all projects or to .claude/skills/ in one project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Start with a natural request. Describe your rough idea and use a trigger phrase such as 'refine this idea' or 'stress-test my plan'.
- 4Answer the sharpening questions. Reply to the three to five questions about who the idea is for, what success looks like and the real constraints.
- 5Review variations and directions. Say which variations resonate, then check the two or three directions and the assumptions named for each.
- 6Save the one-pager if you want it. Confirm when the agent asks, and it will save the markdown one-pager to docs/ideas/[idea-name].md.
What is an agent skill and what does idea-refine do?
An agent skill is a folder containing a SKILL.md file that tells an AI agent how to handle a specific kind of task. When the skill is installed and you ask for something that matches its description, the agent follows the instructions in that file.
The idea-refine skill covers early-stage thinking. It works in three phases. First it restates the idea as a clear problem and asks sharpening questions, then generates several variations. Next it clusters the ideas into two or three directions and tests each one for user value, feasibility and differentiation, naming the assumptions that could sink it. Finally it produces a markdown one-pager.
- Problem statement written as a 'How Might We' framing
- Recommended direction and the reasoning behind it
- Key assumptions to validate, each with a way to test it
- MVP scope, covering what is in and what is out
- A Not Doing list that makes trade-offs explicit
How do you install the idea-refine skill?
Download the ZIP for the skill from this page and unzip it. Then place the idea-refine folder in one of the following locations, depending on whether you want it available everywhere or only in one project.
You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill there.
- Personal (all projects): ~/.claude/skills/idea-refine/
- Single project: .claude/skills/idea-refine/ inside your project root
- Claude apps: Settings → Capabilities → Skills, then upload the skill
~/.claude/skills/idea-refine/How do you trigger the skill with natural requests?
You do not need a special command. The skill's description lists trigger phrases, so the agent will usually pick it up when you describe a vague idea or ask to pressure-test a plan. The skill's own instructions also show a slash-style invocation with an idea, so you can use that form if your runtime supports it.
Good requests state the idea and what you want from the session. The skill asks its own questions, so you do not need to answer everything up front.
- "Ideate on a tool that helps small local restaurants compete with delivery apps"
- "Refine this idea: a shared calendar for climbing gyms"
- "Stress-test my plan to move our reporting into a spreadsheet add-on"
- "Help me refine this idea before I start building it"
What happens during a session?
The agent does not jump straight to an answer. Expect it to ask three to five sharpening questions and to wait for your replies before moving on. Its questions focus on who the idea is for, what success looks like, real constraints, what has been tried before, and why now.
If you are working inside a codebase, the agent can look through the project files to ground its suggestions in existing architecture and patterns. The skill also includes reference files on frameworks and evaluation criteria that it draws on selectively.
- Expect 3-5 sharpening questions, not a long questionnaire
- Answer honestly; the skill is built to push back on weak ideas
- The one-pager is saved to docs/ideas/[idea-name].md only if you confirm
What does the skill need, and what about scripts and network use?
The skill needs an agent runtime that reads SKILL.md files, and Bash so it can run the optional setup script. If you want the output saved, the agent needs filesystem write access in the project root. The skill's listing says it runs scripts and does not use the network.
The optional script is scripts/idea-refine.sh. The skill's documentation says to run it from the project root, because it creates ./docs/ideas. Read the script before running it, since it is a shell script that the skill lists as running scripts. Saving the output is optional and happens only after you confirm.
- Requires: a SKILL.md-compatible agent runtime, Bash, and filesystem write access in the project root if you save output
- Runs scripts: yes (scripts/idea-refine.sh, optional)
- Uses network: no, according to the skill's listing
- Review the script before running it, and run it from the project root
bash <skill-dir>/scripts/idea-refine.shWhat does a good session look like?
A useful session starts with a real idea and a real person in mind. Reply to the sharpening questions with specifics. When the agent proposes variations, say which ones resonate and which do not. Once it narrows to directions, look closely at the assumptions it lists, because the skill treats untested assumptions as the main reason ideas fail.
The skill is designed to be honest rather than encouraging. If an idea is weak, expect the agent to say so and explain why. Treat the Not Doing list as one of the most useful parts of the output.
- Name a specific person who has the problem
- Say what you tried before and why it did not work
- Ask the agent to challenge a direction you like
- Check the Not Doing list for trade-offs you have not accepted
What people use it for
- Pressure-testing a startup concept before committing to a build
- Scoping a product feature and surfacing hidden assumptions
- Deciding what to leave out of a first version through the Not Doing list
- Getting a structured, honest sounding board on a process improvement idea
Frequently asked questions
Is the idea-refine skill free?
The source for this page does not state pricing or licence terms beyond the licence listed as MIT. Check the repository's licence file for the terms that apply to you.
What do I need to run the idea-refine skill?
You need an agent runtime that supports SKILL.md-based skills. Bash is needed to run the optional setup script, and filesystem write access in the project root is needed if you want to save the output.
Where do I install the idea-refine skill?
Place the idea-refine folder in ~/.claude/skills/ to use it across projects, or in .claude/skills/ inside one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Does idea-refine use the internet?
The skill's listing says it does not use the network. It does run scripts, and the optional scripts/idea-refine.sh file creates ./docs/ideas when run from the project root, so review it before use.
What should I use if I don't know what I want yet?
The skill's own documentation points to a different skill, interview-me, for users who are unsure what they want at all. Use that skill first, then return to idea-refine.
What if I already chose a direction and need a detailed spec?
The skill points to spec-driven-development for work where the direction is already chosen and only needs a detailed specification.
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
Idea Refine suits founders, product thinkers and developers who have a rough idea and want it challenged before they build, especially when they want honest pushback and a clear Not Doing list. If you do not yet know what you want, or your direction is already set and you only need a spec, the skill itself recommends interview-me or spec-driven-development instead.
Download the skill