How to write a specsy spec
Everything you need to know to write a spec that builds cleanly, earns great reviews, and sells.
What makes a great spec?
A great spec is the thing you wish existed before you started building. It's specific enough that Claude Code never has to guess, and opinionated enough that every decision is already made.
The best specs have three qualities: clarity (Claude knows exactly what to build), completeness (nothing important is left out), and build order (the steps are sequenced so nothing breaks). Think of it less like documentation and more like a conversation you've already had with Claude, one where you worked out all the tricky parts in advance.
The anatomy of a spec
Every spec on specsy follows the same structure. Buyers expect it, and Claude Code works best with a consistent format.
Required sections:
- What you're building: one short paragraph. What is this app? What problem does it solve?
- Who it's for: the specific person this is built for. "You track your workouts and want…" is better than "fitness enthusiasts."
- Core screens / features: list every screen or major feature. Be specific about what's on each one.
- Tech stack: what framework, database, auth, and third-party services. Explain why briefly. It helps buyers understand the choices.
- Database schema: actual SQL or Prisma schema. Don't leave this out; it's one of the most valuable parts.
- API routes: list every endpoint with its method and purpose.
- Step-by-step build order: this is the magic. Number the steps. Each step should be a discrete chunk Claude can complete and verify before moving on.
Optional but valuable:
- Styling & UX details (colors, fonts, mobile considerations)
- Environment variables checklist
- Common gotchas or things to watch out for
The build order is everything
Most spec authors underestimate how important the build order is. A spec with a bad build order produces a tangled mess halfway through. A spec with a great build order produces a working app in 90 minutes.
The rule: each step should produce something you can run and verify before starting the next.
Bad step: "Build the backend."
Good step: "Create the Supabase tables and RLS policies. Run the SQL in the editor and verify all tables appear in the dashboard."
Start with the database schema, then the data model / types, then the API routes (test each with curl), then the UI from the inside out (data-fetching hooks before components, components before pages). Leave styling and polish for last.
Aim for 8–12 steps. Fewer and each step is too big. More and it becomes tedious.
Be opinionated
Buyers are paying for your expertise. They don't want a spec that says "choose your preferred database". They want you to have already chosen, and explained why.
Opinions that buyers value:
- Framework choice with a reason ("Next.js App Router: SSR for fast first load, API routes keep things simple")
- Auth approach ("magic links only: no password reset flows to build, no OAuth complexity")
- UI library or no UI library ("plain Tailwind: fewer dependencies, easier to customize")
- What to skip ("no unit tests in this spec: the app is simple enough that manual testing is fine for a first build")
Don't hedge. Pick a stack. If there's a genuinely good reason to offer an alternative, put it in a callout box. Don't hedge in the main text.
Writing the "Look Inside" preview
When you upload your spec, specsy automatically extracts the first section and table of contents as the "Look Inside" preview. Buyers see this before purchasing.
This means your introduction and table of contents need to sell the spec. Make sure:
- The first section ("What you're building") is vivid and specific. "A Notion-style note-taking app" tells buyers nothing. "A local-first markdown notebook that syncs to iCloud" tells them exactly what they're getting.
- Your table of contents shows depth. Ten well-named sections signals a thorough spec. Three vague headings does not.
- The tone is confident. You've built this, or you've thought through every detail. Write like it.
Pricing your spec
specsy specs start from $3. Here's how to think about pricing:
$3–5. Simple single-screen apps, utility scripts, or apps with minimal backend. Under an hour to build. Good for your first spec to build reviews.
$5–15. Multi-screen apps with auth, a real database schema, and a couple of API integrations. The sweet spot for most specs.
$15–30. Complex apps with multiple integrations, advanced features, or niche expertise. Only charge this if your spec is genuinely comprehensive and your build order is airtight.
$30–49. Premium, highly specialised builds that save buyers days of architecture work. Think: complex third-party integrations, unusual tech stacks, or deep domain knowledge baked in. You need a track record of strong reviews before pricing here.
Don't underprice out of imposter syndrome. If your spec saves someone three days of architecture decisions and debugging, $15 is a bargain. The purchase count and reviews will tell you if you've priced it right.
Before you submit
Before submitting for review, do this checklist:
- Try building it yourself (or with Claude Code). You'll catch every gap in the spec immediately.
- Check the build order: could a beginner follow each step without getting stuck?
- Paste your spec into Claude Code and ask it: "What questions do you have before starting?" Any question Claude asks is a gap in your spec.
- Check for assumptions: have you assumed the reader knows how to set up Supabase? If so, add a brief note.
- Proofread: specs with typos and unclear sentences get rejected in review.
- Word count check: a spec under 1,000 words is probably too thin. Over 5,000 words is probably too long.
Our review team checks every spec against these same criteria before approving it for sale.
Ready to write your spec?
Create your creator account and submit your first spec for review. Most specs are reviewed within 24 hours.
Start selling on specsy →