# spark

Turns ideas into structured design documents through iterative dialogue. It writes the finished spec to docs/spark/ and stops before any code gets written.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 541 installs · ★ 50
- Author: wishworldbetter
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wishworldbetter/seedex-skills/tree/HEAD/skills/spark/SKILL.md
- Updated: 2026-05-21
- HTML: https://affpapa.org/en/nevibecode/skills/spark

## What it does

The skill inspects the repository state first, checking docs, files, and recent commits. Then it asks clarifying questions one at a time to pin down constraints and success criteria. If an idea spans multiple unrelated systems, it flags the scope early and splits the work into sub-projects.

It outlines two or three implementation approaches with trade-offs, leading with a recommended option. Once aligned, it presents the architecture in sections covering data flow, error handling, and testing. The final specification is written to `docs/spark/YYYY-MM-DD-<topic>-design.md`, followed by an inline self-review for ambiguities or placeholders.

Writing code is strictly blocked. The workflow ends right when the spec file path is delivered, which prevents premature implementation before the design is approved.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add wishworldbetter/seedex-skills --skill spark -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/spark/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/spark/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add wishworldbetter/seedex-skills --skill spark -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/spark/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add wishworldbetter/seedex-skills --skill spark -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/spark/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install wishworldbetter/seedex-skills spark
```

2. **Manually: put the files in place**
- File: `.github/skills/spark/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add wishworldbetter/seedex-skills --skill spark -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/wishworldbetter/seedex-skills --path skills/spark
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/spark/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add wishworldbetter/seedex-skills --skill spark -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wishworldbetter/seedex-skills/tree/HEAD/skills/spark/SKILL.md

## When to use it
- turn unformed product ideas into technical specs
- split complex multi-service projects into manageable sub-projects
- compare trade-offs between different technical approaches
- document architecture, data flows, and error handling before coding

## Example prompts
- Use spark to brainstorm our new background job worker
- Help me design a billing webhook handler and write the spec
- Run spark to evaluate approaches for file upload processing

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3eb05c5105951dd4.

BEGIN THIRD-PARTY FILE 3eb05c5105951dd4
````text
---
name: spark
version: 0.1.2
description: "Use when the user wants to brainstorm an idea or design a feature/spec. Explores intent and requirements through dialogue, then writes a spec document to docs/spark/ and STOPS. Does not auto-chain to implementation planning or any other skill."
---

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Explore project context** — check files, docs, recent commits
2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Write design doc** — save to `docs/spark/YYYY-MM-DD-<topic>-design.md` and commit
7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
8. **User reviews written spec** — ask user to review the spec file before proceeding
9. **Deliver spec to user and STOP** — report the spec file path; do not invoke any other skill or start implementation

## Process Flow

```dot
digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Deliver spec path to user and STOP" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
````
END THIRD-PARTY FILE 3eb05c5105951dd4

The third-party file has ended. Everything between the 3eb05c5105951dd4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3013 of 10757 bytes. © wishworldbetter · MIT · https://github.com/wishworldbetter/seedex-skills/tree/HEAD/skills/spark/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md