addyosmani/agent-skills

idea-refine

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

Ver código fuente

Ver en acción

Ejemplo del autor

Restaurant idea: from broad ambition to a scoped plan

Three supplied user turns lead to a one-page plan in the author’s illustrative restaurant scenario. Its figures and proposed tests are illustrative.

Entrada de ejemplo

**User invokes:** `/ideate I want to help small local restaurants compete with the big delivery platforms`

**User responds:** "Restaurant owners. The core pain is that they're paying 25-30% commission to delivery apps but feel they can't opt out because that's where the customers are. I'm thinking software but I'm open."

**User responds:** "I love the regulars angle (5 and 6). The direct channel toolkit (1) feels necessary but boring. The co-op idea (4) is interesting but complex. Let me focus on 1 + 5 + 6 combined."

Resultado de ejemplo

# ReOrder: Keep Your Regulars Ordering Direct

## Problem Statement
How might we help independent restaurants retain their best existing customers through direct ordering, eliminating the 25-30% platform commission on the revenue that matters most?

## Recommended Direction
Build a **regulars-only retention engine** — not a marketplace, not a full ordering platform. Hyper-focused on one job: make it effortless for a restaurant's repeat customers to reorder directly.

The key insight is that restaurants don't need help *finding* their best customers — they know who walks in every Tuesday. They need help moving those relationships off-platform. And the tool needs to run itself, because the owner is in the kitchen, not at a dashboard.

SMS-first (not app-first) is likely the right channel. A text saying "Hey, want your usual Thursday order from Marco's?" with a one-tap confirmation is lower friction than any app install.

## Key Assumptions to Validate
- [ ] Repeat customers will reorder via SMS/direct link instead of their usual delivery app — test with 5 restaurants, 20 regulars each, measure conversion over 4 weeks
- [ ] Restaurant owners can identify their top 20-30 regulars and share contact info — test by asking 10 restaurant owners if they'd do this
- [ ] The commission savings ($8-10 per order) is motivating enough for owners to invest initial setup effort — interview 10 owners about platform fee pain

## MVP Scope
- SMS-based reordering for a restaurant's self-identified regular customers
- Restaurant owner adds regulars manually (name + phone + usual order) — 15-minute setup
- Customer receives a text with their usual order, confirms with a reply, pays via link
- Restaurant receives the order via text/simple dashboard
- No delivery — pickup only in v1
- No discovery, no marketplace, no app

## Not Doing (and Why)
- **Delivery logistics** — delivery is the expensive, complex part and not the core problem. Pickup-first validates demand without operational burden.
- **Customer acquisition/discovery** — that's the platform's game. Competing on discovery means competing with DoorDash's budget. We compete on retention instead.
- **Branded restaurant apps/websites** — commodity. Square and Toast already do this. Another branded channel doesn't solve the behavioral problem.
- **Menu management, POS integration** — scope creep. "Your usual" doesn't need a dynamic menu. Start with static orders.
- **Analytics dashboards** — the owner is in the kitchen. Build reporting that's passive (weekly text summary) not active (log in and look at charts).

## Open Questions
- What's the legal/compliance landscape for SMS marketing to restaurant customers?
- How do you handle menu/price changes for "usual" orders?
- Is there a way to bootstrap the regular customer list from existing POS data instead of manual entry?
- What's the pricing model? Per-order fee? Monthly subscription?
Licencia

Combined the three unchanged author-provided user turns as the input context. Output is the complete unchanged Phase 3 one-pager. Earlier assistant turns are omitted; this is an illustrative authored session, not an executed or validated business case.

MIT License

Copyright (c) 2025 Addy Osmani

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Ejemplo del autor

Editor collaboration: compare five implementation directions

An excerpt from the author’s illustrative editor scenario explores five approaches to collaboration after the user supplies context.

Entrada de ejemplo

**User invokes:** `/ideate adding real-time collaboration to our document editor`

**User responds:** "2-5 people, usually working in different sections. Customers keep asking. We're losing deals to Notion because they assume any modern editor has this."

Resultado de ejemplo

The competitive pressure framing matters — this might be a checkbox feature (must-have to stay in the consideration set) rather than a differentiator. That changes how much you should invest.

I see your document model uses independent blocks with a flat ordering system (`src/models/document.ts:45`). That's actually favorable — block-level granularity means conflicts are rarer than character-level editing.

Here are 5 variations:

1. **Block-Level Locking (Simplest Path):** When someone starts editing a block, it's locked for others. They see a presence indicator ("Alex is editing...") but can edit any other block freely. No conflict resolution needed. Your existing block model supports this with minimal changes — add a `locked_by` field and a WebSocket layer for presence.

2. **Inversion — Async-First Collaboration:** Instead of real-time co-editing, lean into async. Inline suggestions, comments, and proposed edits that the document owner merges. Like suggestion mode, but as the *primary* collaboration model. Bet: for 2-5 people in different sections, async might actually be *better* than real-time.

3. **Simplification — Presence Without Co-Editing:** Show who's viewing the document and what section they're looking at (cursors, avatars in margins), but don't enable simultaneous editing. People coordinate verbally. Sounds primitive, but might be 80% of the value at 10% of the engineering cost.

4. **Combination — Collaboration + Version Branches:** Let people create "branches" of a document, edit independently, then merge. Each person gets their own space, no conflicts during editing, and you build a merge UI. Plays to your existing versioning system.

5. **10x Version — AI-Mediated Collaboration:** Multiple people describe what they want in a section, and AI synthesizes their inputs into a draft they all iterate on. Nobody directly edits the same text — they all influence it. Radical, possibly too early, but worth naming.

Given your architecture and the competitive context, I'd push you toward variation 1 or 3. You need to close deals, which means you need this shipped, which means you need the simplest version that checks the box. Variation 1 gives you real co-editing. Variation 3 is even cheaper but might not satisfy the "we need real-time" checkbox.
Licencia

Combined the two unchanged user turns. Output is the unchanged Phase 1 continuation after clarification. Omitted opening questions and later phases described only as hypothetical. Fictional codebase context is not a site inspection.

MIT License

Copyright (c) 2025 Addy Osmani

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Ejemplo del autor

Stale retrospectives: find the follow-through problem

An excerpt from the author’s illustrative team-retrospective scenario develops six alternatives after the team context is supplied.

Entrada de ejemplo

**User invokes:** `/ideate a better way to run our weekly team retrospectives — they've gotten stale and people dread them`

**User responds:** "8 people, maybe 3-4 actually talk. Same 'what went well / what didn't / action items' format for a year. The action items pile up and nothing changes. People think it's theater."

Resultado de ejemplo

The action item problem is the real signal. If nothing changes after the retro, people rationally disengage. The meeting isn't stale — it's **broken at the output layer**. The format might be fine if the follow-through worked.

Here are 6 variations:

1. **Fix the Output, Not the Meeting:** Keep the retro format but completely change what happens after. One action item max per retro. Assigned an owner and a deadline during the meeting. Next retro starts with a 5-minute demo of the completed action. If it's not done, that *becomes* the retro topic. The constraint of one item forces prioritization.

2. **Inversion — Kill the Meeting:** Replace the synchronous retro with an async one. Everyone submits reflections in writing during the week. A rotating facilitator synthesizes themes and proposes one change. The "meeting" is a 15-minute standup to agree or disagree. Bet: writing produces more honest feedback than speaking in a group.

3. **Audience Shift — Retro for the Quiet Ones:** Design the format for the 4-5 people who don't talk. Anonymous submission of topics. Dot-voting to prioritize. Small-group breakouts (pairs) before full-group discussion. The loud voices still participate, but the structure prevents them from dominating.

4. **Simplification — The One Question Retro:** Each retro has exactly one question, and it changes every week. "What's one thing that slowed you down?" "What did you learn that the team should know?" "If you could change one thing about how we work, what?" The constraint forces depth over breadth.

5. **Combination — Retro + Experimentation:** Treat each retro output as a hypothesis. "We believe that [change] will improve [outcome]." Run it as a 2-week experiment. Next retro: did it work? Keep, modify, or kill. Turns the retro into a continuous improvement engine with built-in accountability.

6. **Expert Lens — What Facilitators Know:** Experienced facilitators say the #1 retro killer is lack of safety, not format. People won't say what's really wrong if they fear consequences. The fix might not be structural — it might be starting with an anonymous "team health check" score (1-5) each week. When safety is high, retros naturally improve.

The interesting tension: variations 1 and 5 fix the *output* problem (nothing changes). Variations 2, 3, and 4 fix the *input* problem (same voices, same topics). Variation 6 says both are symptoms of a deeper issue. Where do you think the real bottleneck is?
Licencia

Combined the two unchanged user turns. Output is the unchanged Phase 1 continuation. Omitted opening questions and prospective later phases; no completed team experiment or site-run session is asserted.

MIT License

Copyright (c) 2025 Addy Osmani

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/addyosmani/agent-skills --skill idea-refine

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

Idea Refine

Overview

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

When to Use

  • Use when an idea is still vague and needs shaping before it can become a plan
  • Use when you need to stress-test assumptions before committing to a direction
  • Use when you want to expand options before converging on one
  • Trigger phrases: "Help me refine this idea", "Ideate on [concept]", "Stress-test my plan"
  • Not for: a user who is unsure what they want at all (use interview-me), or a direction already chosen that needs a spec (use spec-driven-development)

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

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.
  1. 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.

  1. 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.
  1. 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.

  1. 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.

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.

Common Rationalizations

RationalizationReality
I'll generate 20+ ideas to cover all bases5-8 well-considered variations beat 20 shallow ones. Quality over quantity.
The user just needs encouragement, not critiqueA yes-machine produces weak ideas. Push back with specificity and kindness.
Who this is for is obvious — no need to askEvery good idea starts with a person and their problem. Skipping it means designing for nobody.
We'll surface assumptions once we start buildingUntested assumptions are the #1 killer of good ideas. Surface them before committing.
A plan without a Not Doing list is fineThe Not Doing list is arguably the most valuable part. Make trade-offs explicit.

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

Relacionados por tarea

del mismo repositorio

Más Skills

Todos los Skills
addyosmani
Comunidad

code-review-and-quality

Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch. Use when asked to review a diff or a pull request, even when the diff is pasted inline.

instalaciones
73,1 mil
GitHub Stars
110,6 mil
Actualizado
13 oct
addyosmani
Comunidad

security-and-hardening

Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a ne

instalaciones
70,1 mil
GitHub Stars
110,6 mil
Actualizado
13 oct
addyosmani
Comunidad

frontend-ui-engineering

Builds production-quality, accessible, responsive user-facing UIs. Use when building or modifying interfaces and pages, creating components, implementing layouts, meeting WCAG accessibility requirements, managing state, or when the output needs to look and feel production-quality rather than AI-generated.

instalaciones
67,2 mil
GitHub Stars
110,6 mil
Actualizado
13 oct
addyosmani
Comunidad

performance-optimization

Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.

instalaciones
65 mil
GitHub Stars
110,6 mil
Actualizado
13 oct