Idea Refine skill for Claude Code: turn a vague idea into a one-page plan

Makes your agent turn a vague idea into a one-page plan through questions, variations and stress-testing.

Installs: 63.7K; on skills.sh
Stars: 112.6K; on GitHub
Files: 4; besides SKILL.md
Updated: Nov 2026; last repo commit

idea-refine makes the agent act as an ideation partner. It loads when you say things like ideate, refine this idea or stress-test my plan, restates your idea as a How Might We problem, asks 3 to 5 sharpening questions, offers 5 to 8 variations, then narrows to a direction and names its hidden assumptions.

The end result is a markdown one-pager with a problem statement, recommended direction, key assumptions, MVP scope and a Not Doing list. It saves to docs/ideas/[idea-name].md only after you confirm, and the optional bundled script creates that folder.

Good for

Founders and product people with a rough concept
Developers who want assumptions tested before a plan
Anyone choosing between several directions

Install idea-refine

Claude Code

Copy this prompt.

Install the idea-refine skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill idea-refine

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan".

Sections in SKILL.md

Overview
When to Use
How It Works
Usage
Output
Detailed Instructions
Philosophy
Process
Problem Statement
Recommended Direction
Key Assumptions to Validate
MVP Scope
Not Doing (and Why)
Open Questions
Anti-patterns to Avoid
Tone

Key facts

Author: addyosmani (repo owner)
Installs on skills.sh: 63,719 (Nov 2, 2026)
GitHub stars: 112,555 on the agent-skills repo (Nov 2, 2026)
License: MIT
Last commit: 2026-11-01
What installs: 5 files including SKILL.md: examples.md, frameworks.md, refinement-criteria.md and scripts/idea-refine.sh
Needs: The agent's question tool and file reading when inside a codebase; the bundled script is optional
Works in: Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and more, per the README

What it includes

Restate the idea, ask 3 to 5 questions, generate 5 to 8 variations
Uses lenses such as inversion, constraint removal, audience shift, combination and simplification. Inside a codebase it scans files for context.
Read · Phase 1: Understand and expand
Cluster into 2 or 3 directions, stress-test and surface assumptions
Checks user value, feasibility and differentiation, and says plainly when an idea is weak.
Phase 2: Evaluate and converge
Write a one-pager with a Not Doing list
Problem statement, recommended direction, key assumptions, MVP scope and Not Doing.
Phase 3: Sharpen and ship
Offers to save the one-pager; only saves if you confirm
Path docs/ideas/[idea-name].md or a place you choose.
Write · Save to docs/ideas
Optional script that creates docs/ideas if it is missing
A short bash script that runs mkdir -p docs/ideas and prints a JSON status line.
Runs code · scripts/idea-refine.sh
Extra ideation frameworks such as SCAMPER, JTBD and pre-mortem
Read selectively, not all at once.
Read · frameworks.md
Rubric for user value, feasibility, differentiation and assumptions
Used in Phase 2.
Read · refinement-criteria.md
Worked ideation sessions
Shows what a good session looks like.
Read · examples.md

From the official docs

Permissions

Low risk

It can create a docs/ideas folder and save a file there once you confirm. Check the save path before you say yes.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can create a folder and a file in your project
The bundled script runs mkdir -p docs/ideas, and the one-pager is saved to docs/ideas/[idea-name].md after you confirm.
It reads your code for context
Inside a codebase it uses file search and read tools to ground its ideas in what exists.

Questions

What does idea-refine do?

It guides you through three phases: expand a vague idea into variations, evaluate and narrow to a direction with its assumptions, then write a one-page plan with a Not Doing list.

How do I install idea-refine?

Use the install box above. The README also lists npx skills add addyosmani/agent-skills --skill idea-refine for one skill, and a Claude Code plugin for the whole pack (/plugin marketplace add addyosmani/agent-skills, then /plugin install agent-skills@addy-agent-skills). A one-skill install copies only skills/idea-refine/ and not the repo-level references folder; the README says the skill still works.

Does it write files?

Only after you confirm. It offers to save the one-pager to docs/ideas/[idea-name].md. A bundled script can create the docs/ideas folder first.

How is it different from interview-me or spec-driven-development?

The SKILL.md says not to use it when you are unsure what you want at all (use interview-me), or when a direction is chosen and needs a spec (use spec-driven-development). idea-refine sits between those two.

Will it just agree with me?

No. Its instructions say to be honest, not supportive, and to push back on weak ideas with specifics.

Is it safe to run?

It is mostly conversation. The optional script only creates docs/ideas and prints a status line, and it saves a file only after you confirm.

Does it work in Codex, Cursor or other tools?

The README documents Codex (codex plugin marketplace add addyosmani/agent-skills, then codex plugin add agent-skills@agent-skills, Codex CLI v0.122 or newer), Cursor (copy skills into .cursor/skills/), Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro and others. It says the skills are plain Markdown that work with any agent that accepts instruction files. It does not mention the Claude app.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/idea-refine

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

idea-refine SKILL.md · github.com
addyosmani/agent-skills README · github.com
idea-refine.sh · github.com
idea-refine frameworks.md · github.com
idea-refine refinement-criteria.md · github.com
idea-refine examples.md · github.com