AGENT SKILL

spec-to-repo

Use when the user says 'build me an app', 'create a project from this spec', 'scaffold a new repo', 'generate a starter', 'turn this idea into code', 'bootstrap a project', 'I have requirements and need a codebase', or provides a natural-language project specification and expects a complete, runnable repository. Stack-agnostic: Next.js, FastAPI, Rails, Go, Rust, Flutter, and more.

License 许可
MIT
最近更新
2026-06-04
Stars
★ 2
Forks
0

01 前言 Front Matter

name
spec-to-repo
description
Use when the user says 'build me an app', 'create a project from this spec', 'scaffold a new repo', 'generate a starter', 'turn this idea into code', 'bootstrap a project', 'I have requirements and need a codebase', or provides a natural-language project specification and expects a complete, runnable repository. Stack-agnostic: Next.js, FastAPI, Rails, Go, Rust, Flutter, and more.

02 资源文件 3

03 SKILL.md 正文

Spec to Repo

Turn a natural-language project specification into a complete, runnable starter repository. Not a template filler — a spec interpreter that generates real, working code for any stack.

When to Use

  • User provides a text description of an app and wants code
  • User has a PRD, requirements doc, or feature list and needs a codebase
  • User says "build me an app that...", "scaffold this", "bootstrap a project"
  • User wants a working starter repo, not just a file tree

Not this skill when the user wants a SaaS app with Stripe + Auth specifically — use product-team/saas-scaffolder instead.

Core Workflow

Phase 1 — Parse & Interpret

Read the spec. Extract these fields silently:

Field Source Required
App name Explicit or infer from description yes
Description First sentence of spec yes
Features Bullet points or sentences describing behavior yes
Tech stack Explicit ("use FastAPI") or infer from context yes
Auth "login", "users", "accounts", "roles" if mentioned
Database "store", "save", "persist", "records", "schema" if mentioned
API surface "endpoint", "API", "REST", "GraphQL" if mentioned
Deploy target "Vercel", "Docker", "AWS", "Railway" if mentioned

Stack inference rules (when user doesn't specify):

Signal Inferred stack
"web app", "dashboard", "SaaS" Next.js + TypeScript
"API", "backend", "microservice" FastAPI (Python) or Express (Node)
"mobile app" Flutter or React Native
"CLI tool" Go or Python
"data pipeline" Python
"high performance", "systems" Rust or Go

After parsing, present a structured interpretation back to the user:

## Spec Interpretation

**App:** [name]
**Stack:** [framework + language]
**Features:**
1. [feature]
2. [feature]

**Database:** [yes/no — engine]
**Auth:** [yes/no — method]
**Deploy:** [target]

Does this match your intent? Any corrections before I generate?

Flag ambiguities. Ask at most 3 clarifying questions. If the user says "just build it", proceed with best-guess defaults.

Phase 2 — Architecture

Design the project before writing any files:

  1. Select template — Match to a stack template from references/stack-templates.md
  2. Define file tree — List every file that will be created
  3. Map features to files — Each feature gets at minimum one file/component
  4. Design database schema — If applicable, define tables/collections with fields and types
  5. Identify dependencies — List every package with version constraints
  6. Plan API routes — If applicable, list every endpoint with method, path, request/response shape

Present the file tree to the user before generating:

project-name/
├── README.md
├── .env.example
├── .gitignore
├── .github/workflows/ci.yml
├── package.json / requirements.txt / go.mod
├── src/
│   ├── ...
├── tests/
│   ├── ...
└── ...

Phase 3 — Generate

Write every file. Rules:

  • Real code, not stubs. Every function has a real implementation. No // TODO: implement or pass placeholders.
  • Syntactically valid. Every file must parse without errors in its language.
  • Imports match dependencies. Every import must correspond to a package in the manifest (package.json, requirements.txt, go.mod, etc.).
  • Types included. TypeScript projects use types. Python projects use type hints. Go projects use typed structs.
  • Environment variables. Generate .env.example with every required variable, commented with purpose.
  • README.md. Include: project description, prerequisites, setup steps (clone, install, configure env, run), and available scripts/commands.
  • CI config. Generate .github/workflows/ci.yml with: install, lint (if linter in deps), test, build.
  • .gitignore. Stack-appropriate ignores (node_modules, pycache, .env, build artifacts).

File generation order:

  1. Manifest (package.json / requirements.txt / go.mod)
  2. Config files (.env.example, .gitignore, CI)
  3. Database schema / migrations
  4. Core business logic
  5. API routes / endpoints
  6. UI components (if applicable)
  7. Tests
  8. README.md

Phase 4 — Validate

After generation, run through this checklist:

  • [ ] Every imported package exists in the manifest
  • [ ] Every file referenced by an import exists in the tree
  • [ ] .env.example lists every env var used in code
  • [ ] .gitignore covers build artifacts and secrets
  • [ ] README has setup instructions that actually work
  • [ ] No hardcoded secrets, API keys, or passwords
  • [ ] At least one test file exists
  • [ ] Build/start command is documented and would work

Run scripts/validate_project.py against the generated directory to catch common issues.

Examples

Example 1: Task Management API

Input spec:

"Build me a task management API. Users can create, list, update, and delete tasks. Tasks have a title, description, status (todo/in-progress/done), and due date. Use FastAPI with SQLite. Add basic auth with API keys."

Output file tree:

task-api/
├── README.md
├── .env.example              # API_KEY, DATABASE_URL
├── .gitignore
├── .github/workflows/ci.yml
├── requirements.txt          # fastapi, uvicorn, sqlalchemy, pytest
├── main.py                   # FastAPI app, CORS, lifespan
├── models.py                 # SQLAlchemy Task model
├── schemas.py                # Pydantic request/response schemas
├── database.py               # SQLite engine + session
├── auth.py                   # API key middleware
├── routers/
│   └── tasks.py              # CRUD endpoints
└── tests/
    └── test_tasks.py         # Smoke tests for each endpoint

Example 2: Recipe Sharing Web App

Input spec:

"I want a recipe sharing website. Users sign up, post recipes with ingredients and steps, browse other recipes, and save favorites. Use Next.js with Tailwind. Store data in PostgreSQL."

Output file tree:

recipe-share/
├── README.md
├── .env.example              # DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL
├── .gitignore
├── .github/workflows/ci.yml
├── package.json              # next, react, tailwindcss, prisma, next-auth
├── tailwind.config.ts
├── tsconfig.json
├── next.config.ts
├── prisma/
│   └── schema.prisma         # User, Recipe, Ingredient, Favorite models
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx          # Homepage — recipe feed
│   │   ├── recipes/
│   │   │   ├── page.tsx      # Browse recipes
│   │   │   ├── [id]/page.tsx # Recipe detail
│   │   │   └── new/page.tsx  # Create recipe form
│   │   └── api/
│   │       ├── auth/[...nextauth]/route.ts
│   │       └── recipes/route.ts
│   ├── components/
│   │   ├── RecipeCard.tsx
│   │   ├── RecipeForm.tsx
│   │   └── Navbar.tsx
│   └── lib/
│       ├── prisma.ts
│       └── auth.ts
└── tests/
    └── recipes.test.ts

Example 3: CLI Expense Tracker

Input spec:

"Python CLI tool for tracking expenses. Commands: add, list, summary, export-csv. Store in a local SQLite file. No external API."

Output file tree:

expense-tracker/
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── pyproject.toml
├── src/
│   └── expense_tracker/
│       ├── __init__.py
│       ├── cli.py            # argparse commands
│       ├── database.py       # SQLite operations
│       ├── models.py         # Expense dataclass
│       └── formatters.py     # Table + CSV output
└── tests/
    └── test_cli.py

Anti-Patterns

Anti-pattern Fix
Placeholder code — // TODO: implement, pass, empty function bodies Every function has a real implementation. If complex, implement a working simplified version.
Stack override — picking Next.js when the user said Flask Always honor explicit tech preferences. Only infer when the user doesn't specify.
Missing .gitignore — committing node_modules or .env Generate stack-appropriate .gitignore as one of the first files.
Phantom imports — importing packages not in the manifest Cross-check every import against package.json / requirements.txt before finishing.
Over-engineering MVP — adding Redis caching, rate limiting, WebSockets to a v1 Build the minimum that works. The user can iterate.
Ignoring stated preferences — user says "PostgreSQL" and you generate MongoDB Parse the spec carefully. Explicit preferences are non-negotiable.
Missing env vars — code reads process.env.X but .env.example doesn't list it Every env var used in code must appear in .env.example with a comment.
No tests — shipping a repo with zero test files At minimum: one smoke test per API endpoint or one test per core function.
Hallucinated APIs — generating code that calls library methods that don't exist Stick to well-documented, stable APIs. When unsure, use the simplest approach.

Validation Script

scripts/validate_project.py

Checks a generated project directory for common issues:

# Validate a generated project
python3 scripts/validate_project.py /path/to/generated-project

# JSON output
python3 scripts/validate_project.py /path/to/generated-project --format json

Checks performed:

  • README.md exists and is non-empty
  • .gitignore exists
  • .env.example exists (if code references env vars)
  • Package manifest exists (package.json, requirements.txt, go.mod, Cargo.toml, pubspec.yaml)
  • No .env file committed (secrets leak)
  • At least one test file exists
  • No TODO/FIXME placeholders in generated code

Progressive Enhancement

For complex specs, generate in stages:

  1. MVP — Core feature only, working end-to-end
  2. Auth — Add authentication if requested
  3. Polish — Error handling, validation, loading states
  4. Deploy — Docker, CI, deploy config

Ask the user after MVP: "Core is working. Want me to add auth/polish/deploy next, or iterate on what's here?"

Cross-References

  • Related: product-team/saas-scaffolder — SaaS-specific scaffolding (Next.js + Stripe + Auth)
  • Related: engineering/spec-driven-workflow — spec-first development methodology
  • Related: engineering/database-designer — database schema design patterns
  • Related: engineering-team/senior-fullstack — full-stack implementation patterns

04 同仓库更多 Skills

kruxshnx
kruxshnx/claude-skills-devin

syllabus

Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

research

Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Triggers — "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

pulse

Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

patent

Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

notebooklm

Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM — 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment — fails gracefully when unavailable.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

litreview

Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list — that's a plain Consensus search.

★ 2