New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Idea Refinement

by addyosmani in addyosmani/agent-skills

Guides a conversation that takes a vague idea through divergent and convergent thinking and ends in a markdown one-pager covering scope and assumptions.

MITAuto-check passedAgent Workflows

Install Idea Refinement

skills CLI
$ npx skills add addyosmani/agent-skills --skill idea-refine -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install addyosmani/agent-skills idea-refine --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/addyosmani/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/idea-refine .claude/skills/idea-refine && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
idea-refine
GitHub stars
102k
Used in
6 other repos
Token cost
~2k tokens
SKILL.md length
1,011 words
Files
5 (incl. scripts)
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

Guides a conversation that takes a vague idea through divergent and convergent thinking and ends in a markdown one-pager covering scope and assumptions.

  • Works in 3 steps: Understand & Expand (Divergent) → Evaluate & Converge → Sharpen & Ship
  • An idea is still vague and needs shaping before anyone plans it
  • SKILL.md covers How It Works, Usage, Output and Detailed Instructions, plus 2 more sections
  • Runs Shell scripts from its folder; calls bash

What it does

The agent acts as an ideation partner and moves through three phases. First it restates the idea as a How Might We problem, asks three to five sharpening questions about audience, success, constraints, past attempts and timing, and proposes five to eight variations. Next it clusters the ideas, stress-tests them and brings hidden assumptions to the surface. Last it sharpens the outcome into a concrete one-pager.

After you confirm, the one-pager is saved under docs/ideas with the idea's name and holds a problem statement, a recommended direction, key assumptions, an MVP scope and a Not Doing list. An idea-refine.sh script can set up the ideas directory, and companion files supply examples, frameworks and refinement criteria. The stated philosophy favors the simplest version that solves the real problem, starts from the user experience and challenges every assumption.

When your agent uses it

  • An idea is still vague and needs shaping before anyone plans it
  • Stress-testing the assumptions behind a plan before committing to it
  • Widening the set of options before settling on one direction

Example prompts

  • “Help me refine this idea: a browser extension that summarizes long email threads.”
  • “Stress-test my plan to move our support docs into a searchable help center.”
  • “I want options before I commit, so ideate on ways to onboard new contributors to our open-source project.”

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Understand & Expand (Divergent)
  2. Evaluate & Converge
  3. Sharpen & Ship

What it can do on your machine

Read from SKILL.md and the folder at commit 1401c8b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Idea Refinement loads about 2k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 1,011 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~87
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from addyosmani/agent-skills at commit 1401c8b, republished under its MIT licence (© addyosmani). 1,011 words, ~2,021 tokens.

Download SKILL.mdSave it as .claude/skills/idea-refine/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
idea-refine
description
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".

Idea Refine

Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking.

How It Works

  1. Understand & Expand (Divergent): Restate the idea, ask sharpening questions, and generate variations.
  2. Evaluate & Converge: Cluster ideas, stress-test them, and surface hidden assumptions.
  3. Sharpen & Ship: Produce a concrete markdown one-pager moving work forward.

Usage

This skill is primarily an interactive dialogue. Invoke it with an idea, and the agent will guide you through the process.

bash
# Optional: Initialize the ideas directory
bash skills/idea-refine/scripts/idea-refine.sh

Trigger Phrases:

  • "Help me refine this idea"
  • "Ideate on [concept]"
  • "Stress-test my plan"

Output

The final output is a markdown one-pager saved to docs/ideas/[idea-name].md (after user confirmation), containing:

  • Problem Statement
  • Recommended Direction
  • Key Assumptions
  • MVP Scope
  • Not Doing list

Detailed Instructions

You are an ideation partner. Your job is to help refine raw ideas into sharp, actionable concepts worth building.

Philosophy
  • Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.
  • Start with the user experience, work backwards to technology.
  • Say no to 1,000 things. Focus beats breadth.
  • Challenge every assumption. "How it's usually done" is not a reason.
  • Show people the future — don't just give them better horses.
  • The parts you can't see should be as beautiful as the parts you can.
Process

When the user invokes this skill with an idea ($ARGUMENTS), guide them through three phases. Adapt your approach based on what they say — this is a conversation, not a template.

Phase 1: Understand & Expand (Divergent)

Goal: Take the raw idea and open it up.

  1. Restate the idea as a crisp "How Might We" problem statement. This forces clarity on what's actually being solved.

  2. Ask 3-5 sharpening questions — no more. Focus on:

    • Who is this for, specifically?
    • What does success look like?
    • What are the real constraints (time, tech, resources)?
    • What's been tried before?
    • Why now?

    Use the AskUserQuestion tool to gather this input. Do NOT proceed until you understand who this is for and what success looks like.

  3. Generate 5-8 idea variations using these lenses:

    • Inversion: "What if we did the opposite?"
    • Constraint removal: "What if budget/time/tech weren't factors?"
    • Audience shift: "What if this were for [different user]?"
    • Combination: "What if we merged this with [adjacent idea]?"
    • Simplification: "What's the version that's 10x simpler?"
    • 10x version: "What would this look like at massive scale?"
    • Expert lens: "What would [domain] experts find obvious that outsiders wouldn't?"

    Push beyond what the user initially asked for. Create products people don't know they need yet.

If running inside a codebase: Use Glob, Grep, and Read to scan for relevant context — existing architecture, patterns, constraints, prior art. Ground your variations in what actually exists. Reference specific files and patterns when relevant.

Read frameworks.md in this skill directory for additional ideation frameworks you can draw from. Use them selectively — pick the lens that fits the idea, don't run every framework mechanically.

Phase 2: Evaluate & Converge

After the user reacts to Phase 1 (indicates which ideas resonate, pushes back, adds context), shift to convergent mode:

  1. Cluster the ideas that resonated into 2-3 distinct directions. Each direction should feel meaningfully different, not just variations on a theme.

  2. Stress-test each direction against three criteria:

    • User value: Who benefits and how much? Is this a painkiller or a vitamin?
    • Feasibility: What's the technical and resource cost? What's the hardest part?
    • Differentiation: What makes this genuinely different? Would someone switch from their current solution?

    Read refinement-criteria.md in this skill directory for the full evaluation rubric.

  3. Surface hidden assumptions. For each direction, explicitly name:

    • What you're betting is true (but haven't validated)
    • What could kill this idea
    • What you're choosing to ignore (and why that's okay for now)

    This is where most ideation fails. Don't skip it.

Be honest, not supportive. If an idea is weak, say so with kindness. A good ideation partner is not a yes-machine. Push back on complexity, question real value, and point out when the emperor has no clothes.

Show full SKILL.md (356 more words)Show less
Phase 3: Sharpen & Ship

Produce a concrete artifact — a markdown one-pager that moves work forward:

markdown
# [Idea Name]

## Problem Statement
[One-sentence "How Might We" framing]

## Recommended Direction
[The chosen direction and why — 2-3 paragraphs max]

## Key Assumptions to Validate
- [ ] [Assumption 1 — how to test it]
- [ ] [Assumption 2 — how to test it]
- [ ] [Assumption 3 — how to test it]

## MVP Scope
[The minimum version that tests the core assumption. What's in, what's out.]

## Not Doing (and Why)
- [Thing 1] — [reason]
- [Thing 2] — [reason]
- [Thing 3] — [reason]

## Open Questions
- [Question that needs answering before building]

The "Not Doing" list is arguably the most valuable part. Focus is about saying no to good ideas. Make the trade-offs explicit.

Ask the user if they'd like to save this to docs/ideas/[idea-name].md (or a location of their choosing). Only save if they confirm.

Anti-patterns to Avoid
  • Don't generate 20+ ideas. Quality over quantity. 5-8 well-considered variations beat 20 shallow ones.
  • Don't be a yes-machine. Push back on weak ideas with specificity and kindness.
  • Don't skip "who is this for." Every good idea starts with a person and their problem.
  • Don't produce a plan without surfacing assumptions. Untested assumptions are the #1 killer of good ideas.
  • Don't over-engineer the process. Three phases, each doing one thing well. Resist adding steps.
  • Don't just list ideas — tell a story. Each variation should have a reason it exists, not just be a bullet point.
  • Don't ignore the codebase. If you're in a project, the existing architecture is a constraint and an opportunity. Use it.
Tone

Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a facilitator reading from a script. Channel the energy of "that's interesting, but what if..." -- always pushing one step further without being exhausting.

Read examples.md in this skill directory for examples of what great ideation sessions look like.

Red Flags

  • Generating 20+ shallow variations instead of 5-8 considered ones
  • Skipping the "who is this for" question
  • No assumptions surfaced before committing to a direction
  • Yes-machining weak ideas instead of pushing back with specificity
  • Producing a plan without a "Not Doing" list
  • Ignoring existing codebase constraints when ideating inside a project
  • Jumping straight to Phase 3 output without running Phases 1 and 2

Verification

After completing an ideation session:

  • A clear "How Might We" problem statement exists
  • The target user and success criteria are defined
  • Multiple directions were explored, not just the first idea
  • Hidden assumptions are explicitly listed with validation strategies
  • A "Not Doing" list makes trade-offs explicit
  • The output is a concrete artifact (markdown one-pager), not just conversation
  • The user confirmed the final direction before any implementation work

© addyosmani, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (scripts) in skills/idea-refine of addyosmani/agent-skills.

  • SKILL.md
  • examples.md
  • frameworks.md
  • refinement-criteria.md
  • scripts/idea-refine.sh

Open the folder on GitHubat commit 1401c8b

Used in 6 other repositories

We found 10 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 6 other GitHub owners. This page covers the copy in addyosmani/agent-skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Idea Refinement next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Idea Refinement compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Idea Refinement this skilladdyosmani/agent-skills102k6 repos~2kAutomated safety check: PassMIT
YC Office Hoursgarrytan/gstack136k—~4.2kAutomated safety check: PassMIT
Team OKR Brainstormphuryn/pm-skills27k—~1.1kAutomated safety check: PassMIT
Bmad Product Briefaj-geddes/claude-code-bmad-skills487—~1.7kAutomated safety check: NotesCustom licence
Yao Demand Skillyaojingang/yao-open-skills1.3k—~1.4kAutomated safety check: PassMIT
Andreessenalirezarezvani/claude-skills28k—~3kAutomated safety check: PassMIT

Similar skills

  • YC Office Hours

    garrytan/gstack

    Runs a YC-style office hours session that pressure-tests a product idea before any code and ends in a design document instead of an implementation.

    136k GitHub stars~4.2k tokensUpdated today
    Product & Project ManagementAuto-check passed

  • Team OKR Brainstorm

    phuryn/pm-skills

    Drafts three alternative sets of team OKRs, each with an inspiring objective and measurable key results, tied to the company strategy you provide.

    27k GitHub stars~1.1k tokensUpdated 22 days ago
    Product & Project ManagementAuto-check passed

  • Bmad Product Brief

    aj-geddes/claude-code-bmad-skills

    Lean facilitator for creating, updating, and validating a product brief — the Analysis-phase foundation of the BMAD Method.

    487 GitHub stars~1.7k tokensUpdated 3 mo ago
    Product & Project ManagementAuto-check: notes

  • Yao Demand Skill

    yaojingang/yao-open-skills

    Evaluate product demand from product links, product descriptions, PRDs, websites, app-store pages, white papers, sales decks, screenshots, or funding materials using the demand triangle model: lack…

    1.3k GitHub stars~1.4k tokensUpdated 1 mo ago
    Product & Project ManagementAuto-check passed

  • Andreessen

    alirezarezvani/claude-skills

    Marc Andreessen-mode decision and productivity skill. An agent skill from alirezarezvani/claude-skills.

    28k GitHub stars~3k tokensUpdated 1 mo ago
    Product & Project ManagementAuto-check passed

  • Product Vision

    phuryn/pm-skills

    Brainstorm an inspiring, achievable, and emotional product vision that motivates teams and aligns stakeholders.

    27k GitHub stars~629 tokensUpdated 22 days ago
    Product & Project ManagementAuto-check passed

More from addyosmani/agent-skills

All 12 skills in this repo

  • Interview Me

    addyosmani/agent-skills

    Asks one question at a time, each with a best guess attached, until the agent is about 95 percent sure what you really want, before any plan, spec or code.

    102k GitHub starsUsed in 6 repos~3.8k tokens
    Auto-check passed

  • Using Agent Skills

    addyosmani/agent-skills

    Meta-skill for choosing which workflow skill fits the task at hand, plus always-on habits: surface assumptions, stop on confusion, push back, keep it simple and stay in scope.

    102k GitHub starsUsed in 4 repos~2.4k tokens
    Auto-check passed

  • Browser Testing with Chrome DevTools

    addyosmani/agent-skills

    Connects an agent to a real Chrome instance through the Chrome DevTools MCP server, so it can inspect the DOM, read console errors and profile performance directly.

    102k GitHub starsUsed in 4 repos~3.5k tokens
    Auto-check: warnings

  • Constraint-Driven Development

    addyosmani/agent-skills

    Records a project's quality bar in CONSTRAINTS.md and watches diffs for signs an agent quietly weakened it, such as suppressions, skipped tests or lowered thresholds.

    102k GitHub starsUsed in 2 repos~5.2k tokens
    Auto-check passed

  • Git Workflow and Versioning

    addyosmani/agent-skills

    Sets git habits for every change: short-lived branches, atomic commits with descriptive messages, clean pull requests, plus versioning, tagging and changelogs for releases.

    102k GitHub starsUsed in 2 repos~3.5k tokens
    Auto-check: notes

  • Debugging and Error Recovery

    addyosmani/agent-skills

    Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.

    102k GitHub starsUsed in 1 repo~2.6k tokens
    Auto-check passed

Categories

Questions about Idea Refinement

What does Idea Refinement do?

Guides a conversation that takes a vague idea through divergent and convergent thinking and ends in a markdown one-pager covering scope and assumptions. The agent acts as an ideation partner and moves through three phases. First it restates the idea as a How Might We problem, asks three to five sharpening questions about audience, success, constraints, past attempts and timing, and proposes five to eight variations.

When should I use Idea Refinement?

Idea Refinement fits situations like: an idea is still vague and needs shaping before anyone plans it; stress-testing the assumptions behind a plan before committing to it; widening the set of options before settling on one direction.

How do I install Idea Refinement in Claude Code?

Run `npx skills add addyosmani/agent-skills --skill idea-refine -a claude-code`. Or copy the skill folder (skills/idea-refine in addyosmani/agent-skills) into .claude/skills/idea-refine in your project. Claude Code loads it when a task matches its description.

How do I install Idea Refinement in Codex?

Run `npx skills add addyosmani/agent-skills --skill idea-refine -a codex`. Or copy the skill folder (skills/idea-refine in addyosmani/agent-skills) into .agents/skills/idea-refine in your project. Codex loads it when a task matches its description.

Can I use Idea Refinement in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add addyosmani/agent-skills --skill idea-refine -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/idea-refine, .gemini/skills/idea-refine, .github/skills/idea-refine and .opencode/skills/idea-refine in your project.

What does Idea Refinement need to run?

Going by SKILL.md and its folder, Idea Refinement needs a shell for the scripts in its folder and the command-line tools its instructions call (bash).

Does Idea Refinement access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Idea Refinement safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Idea Refinement use?

Idea Refinement is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Idea Refinement use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Idea Refinement?

Skills that share tags, products or a category with Idea Refinement: YC Office Hours (garrytan/gstack, 136k stars), Team OKR Brainstorm (phuryn/pm-skills, 27k stars), Bmad Product Brief (aj-geddes/claude-code-bmad-skills, 487 stars) and Yao Demand Skill (yaojingang/yao-open-skills, 1.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Idea Refinement?

addyosmani (a GitHub user) maintains it in addyosmani/agent-skills, which has 102,135 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 3, 2026.

Source: addyosmani/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.