Documentation Menu

If you already have a spec written in Spec Kit, BMAD, Ralph’s prd.json, or a custom format, you can publish it to SpecMarket without rewriting it. SpecMarket accepts any format.

Supported Formats

SpecMarket works with:

  • Spec Kit — The structured YAML + markdown format with comprehensive documentation
  • BMAD — Behavioral Modeling Approach Design, methodology-focused specs
  • Ralph — Minimal prd.json format, git-friendly and lightweight
  • Custom — Any well-organized spec structure with clear requirements and success criteria
  • Mixed — Projects using multiple formats for different specs

General Requirements

Regardless of format, your spec must include:

  1. Description — What you’re building (1-3 sentences)
  2. Requirements — What the spec builds (detailed, specific)
  3. Success Criteria — How to know it works (testable, measurable)
  4. Technology Stack — Languages, frameworks, libraries, external services required
  5. Infrastructure — Cost estimates, dependencies, resource requirements

Publishing Steps

1. Organize Your Spec

Structure your spec as a directory that can be executed by an AI agent:

Spec Kit format:

my-docusign-replacement/
├── spec.yaml            # Metadata
├── SPEC.md              # Requirements
├── SUCCESS_CRITERIA.md  # What success looks like
├── PROMPT.md            # Instructions for the agent
└── stdlib/              # Tech stack, patterns
    └── STACK.md

BMAD or custom format:

my-docusign-replacement/
├── README.md            # Overview and context
├── REQUIREMENTS.md      # Detailed requirements
├── SUCCESS.md           # Testing and verification
├── PROCESS.md           # Building methodology (if using BMAD)
└── EXAMPLES/            # Example inputs/outputs
    └── sample.json

Ralph prd.json format:

my-docusign-replacement/
├── prd.json             # Complete spec in JSON
└── README.md            # Supporting documentation

The key is clarity. The agent reads your spec, understands the requirements, and builds the software. Format doesn’t matter. Clarity does.

2. Test Your Spec

Before publishing, run it locally with the SpecMarket CLI to verify it works:

specmarket run ./my-docusign-replacement

Watch the build in real-time. The agent will:

  1. Read your spec
  2. Build the application
  3. Run your success criteria
  4. Report results

If the run succeeds, your spec is ready to publish.

If it fails or partially succeeds:

  • Review the agent’s output
  • Update the spec to clarify ambiguities
  • Re-test
  • Repeat until success

3. Validate the Spec

SpecMarket checks for security issues before publishing (data exfiltration, prompt injection, obfuscated code):

specmarket validate ./my-docusign-replacement

If validation passes, you’re ready to publish.

4. Publish to SpecMarket

cd my-docusign-replacement
specmarket publish

When prompted, provide:

  • Scoped name — @yourname/spec-name (yours only; use your SpecMarket username)
  • Display name — “DocuSign Replacement” (human-readable title)
  • Format tag — speckit, bmad, ralph, custom, or mixed
  • Description — What your spec builds (50-200 characters)
  • Infrastructure costs — Estimated API costs, hosting, dependencies
  • Tags — Search keywords: document-signing, contracts, e-signature

The CLI uploads your spec and runs a security scan. Once verified, your spec is listed on SpecMarket.

5. Monitor and Update

After publishing:

  • Watch the metrics: Success rate, average cost, average build time update as people run your spec
  • Read the feedback: Check ratings and community comments
  • Plan improvements: If the success rate is below 90%, consider spec updates to clarify ambiguous requirements
  • Publish versions: Use specmarket publish --version 1.1 to publish an updated version without removing the original

Format-Specific Tips

Publishing a Spec Kit Spec

Spec Kit already follows SpecMarket conventions closely. Minimal changes needed:

  1. Ensure spec.yaml includes all metadata
  2. Verify SUCCESS_CRITERIA.md contains testable criteria
  3. Test with specmarket run
  4. Publish with specmarket publish

Publishing a BMAD Spec

BMAD specs focus on systematic behavior modeling. When publishing:

  1. Include a clear behavior/outcome mapping
  2. Document state machines or decision trees if present
  3. Ensure success criteria align with behavioral requirements
  4. Tag as bmad format
  5. Note in the description that this spec uses BMAD methodology (helps creators familiar with BMAD find it)

Publishing a Ralph Spec

Ralph’s minimal prd.json format is efficient and git-friendly:

  1. Ensure prd.json is complete (requirements, not just high-level vision)
  2. Include a supporting README.md with context and examples
  3. Add success criteria (can be inline in prd.json or in a separate SUCCESS.md)
  4. Tag as ralph format
  5. Test thoroughly—minimal format means less room for implicit context

Publishing a Custom Format

If your spec doesn’t fit existing formats:

  1. Document the format clearly in a FORMAT.md or README.md
  2. Use consistent file naming and structure
  3. Make success criteria explicit and testable
  4. Tag as custom format
  5. Include examples of successful runs (optional but helpful)

Visibility and Discoverability

Your spec’s visibility depends on:

  1. Success rate — Specs with higher success rates rank higher in search
  2. Tags — Ensure tags match what users search for
  3. Update frequency — Active specs (recent versions, maintained) get priority
  4. Community ratings — Users can rate specs; high ratings improve visibility
  5. Bounties — Bounties attached to specs increase visibility

Updating Your Published Spec

To update a published spec:

# Make changes to your spec
# Update spec.yaml or equivalent with new version
 
specmarket publish --update

This creates a new version of your spec without removing the original. Users can see both versions and choose which to run.

Compatibility with Other Tools

If your spec is also published elsewhere:

  • Spec Kit registry — Publish to both SpecKit and SpecMarket. Different audiences and different use cases (Spec Kit focuses on authoring, SpecMarket on execution + distribution).
  • Custom registry — SpecMarket doesn’t restrict where else you publish. Cross-publish as you see fit.
  • No sync needed — Each platform is independent. Updates to one don’t automatically sync to the other. Manage versions separately if needed.

FAQ

Q: Will my spec be publicly visible immediately after publishing? A: After the security scan passes (usually <1 minute), yes. Your spec is listed in search results and browse categories immediately.

Q: Can I make my spec private? A: Not yet. SpecMarket is designed for public, discoverable specs. If you need a private registry, see the Enterprise plan.

Q: What if someone copies my spec? A: Specs are version-controlled and attributed. If someone forks your spec, the fork shows the original author and links to your version. The marketplace tracks lineage.

Q: How do I handle dependencies outside the package manager? A: Document them in infrastructure or the equivalent section. If your spec needs Postgres, API keys, or external services, list them clearly. Users see these requirements before running.

Q: My spec works locally but fails on SpecMarket. Why? A: Most common causes: API keys missing, wrong environment variables, or implicit dependencies not documented. Review the run output, update your spec, and re-publish.

Next steps: