Using SpecMarket with Spec Kit

Spec Kit and SpecMarket solve different problems.

Spec Kit is a spec authoring toolkit. It gives you a structured format — YAML metadata, markdown requirements, clear success criteria — and tools for writing better specs. If you use Spec Kit, you’ve already done the hard work: you have a well-organized, machine-readable description of what you want to build.

SpecMarket is the execution and distribution layer. It takes your spec, runs it in a sandboxed environment, verifies the output against your success criteria, and makes it available to other developers. If you’re building something useful with Spec Kit, SpecMarket is how other people find and run your work without starting from scratch.

This guide shows you how to use both together.

What Each Tool Does

They don’t overlap. Spec Kit makes you a better spec author. SpecMarket makes your spec available and executable.

The Workflow

Write spec in Spec Kit → Test locally with SpecMarket CLI → Publish to SpecMarket registry

Step 1: Author Your Spec with Spec Kit

Follow Spec Kit’s standard structure. A Spec Kit project typically looks like this:

my-invoicing-spec/
├── spec.yaml            # Metadata: name, version, description, tags
├── SPEC.md              # Requirements: what the agent must build
├── SUCCESS_CRITERIA.md  # Verification: how to know it worked
├── PROMPT.md            # Agent instructions: how to approach the task
└── stdlib/
    └── STACK.md         # Tech stack: languages, frameworks, dependencies

Write complete success criteria. This is the most important part for SpecMarket. Your SUCCESS_CRITERIA.md defines the acceptance tests that run after every build. Vague criteria (“it should work”) produce low success rates. Specific criteria (“a POST to /api/invoices returns a 201 with a valid JSON invoice object containing id, amount, currency, status”) produce reliable runs.

See Advanced Authoring for patterns that improve spec quality and success rates.

Step 2: Add SpecMarket Metadata

SpecMarket needs a small amount of additional metadata that Spec Kit’s spec.yaml may not include. Add a specmarket.yaml file to your spec directory:

# specmarket.yaml
name: "@yourname/invoicing-app"     # Scoped name — use your SpecMarket username
displayName: "Invoicing Application"
description: "Replaces FreshBooks for small teams. Invoice generation, payment tracking, PDF export."
replacesSaaS: "freshbooks"          # Optional: SaaS product this replaces
monthlyCostBefore: 17              # Optional: cost of the SaaS/month in USD
infraCost: 0                       # Estimated per-run infrastructure cost in cents
tags:
  - invoicing
  - payments
  - small-business
serviceCategory: finance
primaryStack: node

The specmarket.yaml is separate from spec.yaml so Spec Kit’s metadata and SpecMarket’s registry metadata don’t conflict. You can also provide this metadata interactively when you run specmarket publish.

Step 3: Test with the SpecMarket CLI

Before publishing, run your spec locally to verify it works:

specmarket run ./my-invoicing-spec

The CLI runs your spec in a sandboxed environment, executes the build, then runs your success criteria. You get a detailed output:

Running @yourname/invoicing-app...
  ✓ SPEC.md loaded (2,847 words)
  ✓ STACK.md loaded (Node.js, Express, PostgreSQL)
  ✓ Agent build started
  ...build output...
  ✓ Build complete (47s)

Running success criteria...
  ✓ POST /api/invoices returns 201 with valid invoice object
  ✓ PDF generation produces valid PDF
  ✓ Payment status webhook updates invoice status
  ✗ GET /api/invoices returns paginated list

3/4 criteria passed. Spec not yet ready to publish.
Review: GET /api/invoices pagination not implemented.

Fix the spec or implementation issues and re-test until all criteria pass.

Step 4: Validate the Spec

SpecMarket runs a security scan before publishing:

specmarket validate ./my-invoicing-spec

Validation checks for:

• Data exfiltration patterns (specs that attempt to send data to external services)
• Prompt injection attempts
• Obfuscated or misleading instructions

If your spec is legitimate, validation completes in seconds.

Step 5: Publish

cd my-invoicing-spec
specmarket publish

Your spec is uploaded, security-scanned, and listed in the SpecMarket registry. Anyone with the CLI can then find and run it:

# Another developer, anywhere
specmarket search invoicing
specmarket run @yourname/invoicing-app

Keeping Specs in Sync

If you iterate on your spec in Spec Kit, update the SpecMarket version too:

# After updating SPEC.md, SUCCESS_CRITERIA.md, or PROMPT.md:
specmarket run ./my-invoicing-spec        # Verify it still works
specmarket publish --update              # Publish as a new version

SpecMarket preserves all previous versions. Users can run specific versions:

specmarket run @yourname/invoicing-app@1.0
specmarket run @yourname/invoicing-app@1.1

Publishing Across Registries

SpecMarket and Spec Kit’s registry are independent. You can publish to both:

• Spec Kit registry — Discovery for Spec Kit users, focused on spec structure and documentation
• SpecMarket — Discovery for runners, focused on execution history, success rates, and cost

Publishing to one doesn’t require or conflict with publishing to the other. Update versions separately if you maintain presence in both.

Format Compatibility

Spec Kit’s structure maps directly to SpecMarket’s execution model:

No format conversion needed. SpecMarket reads Spec Kit structure natively.

Success Rate and Quality Metrics

Once published, your spec accumulates performance data across all runs:

• Success rate — % of runs that pass all success criteria
• Average cost — Average API + infra cost per run
• Average build time — Typical time from start to verification
• Steering frequency — How often runs required human steering to complete

High success rates (>90%) indicate a well-specified spec. Lower rates indicate ambiguous requirements or underspecified success criteria. SpecMarket surfaces this data publicly so runners can make informed decisions.

If your success rate drops after publishing, the most common causes are:

1. Success criteria that rely on external state (network calls, third-party APIs that changed)
2. Spec requirements that an agent can satisfy in multiple ways, some of which fail your criteria
3. Dependencies that require specific versions not pinned in STACK.md

The Advanced Authoring guide covers patterns for writing specs that stay above 90%.

FAQ

Q: Do I need a Spec Kit account to publish to SpecMarket? No. SpecMarket is independent. You need a SpecMarket account (free), not a Spec Kit account.

Q: My spec is published on the Spec Kit registry. Do I need to change anything? No. Keep it on the Spec Kit registry as-is. Add specmarket.yaml to the directory and publish to SpecMarket as a separate action.

Q: Can I add SpecMarket run results to my Spec Kit spec? Yes — and it’s a great idea. Once your spec has run data (success rate, cost), add a badge or a “Performance” section to your Spec Kit documentation that links to the SpecMarket listing. Runners want evidence before they invest time in a spec.

Q: What if my Spec Kit spec has multiple variants or configurations? Publish each variant as a separate spec on SpecMarket with distinct scoped names: @yourname/invoicing-app-lite, @yourname/invoicing-app-full. They accumulate independent success rates.

Q: Does SpecMarket modify my spec files when I publish? No. Your spec is stored as-is. SpecMarket adds a specmarket.yaml sidecar for registry metadata, but your original Spec Kit files are not modified.

Next Steps

• Publishing Existing Specs — Overview of all supported formats
• Advanced Authoring — Patterns for high-success-rate specs
• Getting Started — If you’re new to the SpecMarket CLI