Spec To Repo
Install this when you have a messy natural-language product spec and need a structured requirements table, sensible stack defaults, and ambiguity resolved before scaffolding a repo.
Overview
Spec-to-repo is an agent skill most often used in Validate (also Build) that parses ambiguous natural-language specs into structured requirements and default technical choices.
Install
npx skills add https://github.com/alirezarezvani/claude-skills --skill spec-to-repoWhat is this skill?
- Two-pass parsing: full read, then structured interpretation table without over-questioning
- Four-tier extraction priority: explicit statements, strong signals, inference, domain defaults
- Default stack matrix for web UI, API-only, mobile, CLI, performance, and lightweight specs
- Database defaults keyed to auth, persistence, and scale signals—including when not to add a DB
- Ambiguity resolution rules so agents do not stall on unspecified frameworks
- Extraction priority: 4 tiers (explicit, strong signals, contextual inference, defaults)
- Default stack table: 6 spec patterns (web UI, API, mobile, CLI, simple, performance)
Adoption & trust: 526 installs on skills.sh; 17.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your idea lives in chat or a loose doc and the agent keeps guessing stack, data model, and scope boundaries inconsistently.
Who is it for?
Solo builders past the napkin stage who have a written spec (even partial) and want one consistent requirements pass before repo creation.
Skip if: Repos that already have an approved technical design doc, or tasks that are pure debugging with no spec to parse.
When should I use this skill?
User provides ambiguous, incomplete, or conversational natural-language specifications and needs structured requirements before implementation or repo setup.
What do I get? / Deliverables
You get an explicit structured interpretation—explicit vs inferred requirements and defensible defaults—ready to scaffold or invoke implementation planning next.
- Structured interpretation / requirements table
- Documented stack and database defaults with reasoning
- Explicit vs inferred requirement boundaries
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Turning vague intent into explicit scope and technical choices is Validate work that directly feeds the first Build commits. The guide extracts requirements, inference tiers, and default stacks—classic scope definition before implementation.
Where it fits
Turn a paragraph-style SaaS idea into explicit auth, CRUD, and PostgreSQL assumptions.
Produce a structured interpretation table the agent uses before generating folder structure or tickets.
Clarify whether the user wants API-only FastAPI or a Next.js UI before spike code.
Normalize a brainstorm dump into signals strong enough to pick CLI Python vs Go.
How it compares
Requirements extraction and defaulting—not a code generator or deployment skill by itself.
Common Questions / FAQ
Who is spec-to-repo for?
Indie developers and agent users translating NL product descriptions into scoped builds across web apps, APIs, CLIs, and mobile when stack choices are underspecified.
When should I use spec-to-repo?
In Validate → scope when narrowing what to build; in Build → pm when turning an approved brief into implementation-ready requirements before codegen or scaffolding.
Is spec-to-repo safe to install?
It is procedural parsing guidance with no mandated shell or network tools in the excerpt; review the Security Audits panel on this Prism page for the full package.
SKILL.md
READMESKILL.md - Spec To Repo
# Spec Parsing Guide How to extract structured requirements from ambiguous, incomplete, or conversational natural-language specifications. --- ## Parsing Strategy Read the full spec once. On the second pass, extract fields into the structured interpretation table. Don't ask questions for anything you can reasonably infer. ### Extraction Priority 1. **Explicit statements** — "Use PostgreSQL", "Build with Next.js" — non-negotiable 2. **Strong signals** — "users can sign up" implies auth + user model + database 3. **Contextual inference** — "dashboard" implies web app; "track expenses" implies CRUD + database 4. **Defaults** — When nothing is specified, pick the most common choice for the domain --- ## Ambiguity Resolution ### Stack Not Specified | Spec pattern | Default stack | Reasoning | |---|---|---| | Web app with UI | Next.js + TypeScript | Most versatile, SSR + API routes | | API / backend only | FastAPI | Fast to scaffold, great DX, typed | | Mobile app | Flutter | Cross-platform, single codebase | | CLI tool | Python | Fastest to ship, stdlib-rich | | "Simple" / "lightweight" | Express or Flask | Minimal overhead | | "Fast" / "performance" | Go | Compiled, concurrent | ### Database Not Specified | Signal | Default | |---|---| | User accounts, persistent data | PostgreSQL | | Small project, local-only, CLI | SQLite | | Document-oriented, flexible schema | MongoDB (only if user signals) | | No data persistence mentioned | No database — don't add one | ### Auth Not Specified | Signal | Default | |---|---| | "Users", "accounts", "login" | Yes — session-based or JWT | | "Admin panel", "roles" | Yes — with role-based access | | API with "API keys" | Yes — API key middleware | | No user-facing features | No auth — don't add one | --- ## Common Spec Shapes ### Shape 1: Stream of Consciousness > "I want an app where people can post recipes and other people can comment on them and save their favorites, maybe add a rating system too, and it should look nice on mobile" **Extract:** - Features: post recipes, comment, favorites, ratings - UI: responsive / mobile-friendly - Implies: auth (users), database (recipes, comments, favorites, ratings), web app ### Shape 2: Feature List > "Features: 1. User registration 2. Create projects 3. Invite team members 4. Kanban board 5. File uploads" **Extract:** - Features: numbered list, each gets a route/component - Auth: yes (registration) - Database: yes (users, projects, teams, files) - Complex features: kanban (drag-drop), file uploads (storage) ### Shape 3: Technical Spec > "FastAPI backend with PostgreSQL. Endpoints: POST /items, GET /items, GET /items/{id}, PUT /items/{id}, DELETE /items/{id}. Use SQLAlchemy ORM. Add JWT auth." **Extract:** - Stack: explicit (FastAPI, PostgreSQL, SQLAlchemy, JWT) - API: 5 CRUD endpoints, fully defined - Minimal inference needed — generate exactly what's asked ### Shape 4: Existing PRD > [Multi-page document with overview, user personas, feature requirements, acceptance criteria] **Extract:** - Read the overview first for scope - Map feature requirements to files - Use acceptance criteria as test case seeds - Ignore personas, market analysis, timelines — they don't affect code generation --- ## What to Ask vs. What to Infer **Ask (max 3 questions):** - Stack preference when the spec is truly ambiguous and could go multiple ways - Database choice when both SQL and NoSQL are equally valid - Deploy target when it materially affects the code (serverless vs. container) **Infer silently:** - Auth method (JWT for APIs, session for web apps) - Testing framework (most popular for the stack) - Linter / formatter (stack default) - CSS approach (Tailwind for React/Next, stack default otherwise) - Package versions (latest stable) **Never ask:** - "What folder structure do you want?" — use the stack convention - "Do you want TypeScript?" — yes, always for JS projects - "Should I add error handling?" — yes, always - "Do you want tests?" — y