specdown

Author, run, and validate executable specifications in Markdown.

9|3|Updated Apr 9, 2026
One-click install
npx skills add https://github.com/corca-ai/charness --skill specdown
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: specdown
Source: https://github.com/corca-ai/charness/tree/main/plugins/charness/support/specdown
Command: npx skills add https://github.com/corca-ai/charness --skill specdown

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Specdown enables teams to author, run, and validate executable specifications directly in Markdown, blending documentation with verifiable tests.

Core Features & Use Cases

  • Write and execute executable specs inside Markdown with minimal setup
  • Support for shell blocks, inline assertions, check tables, Alloy models, and traceability
  • Use cases span CLI workflows, API specs, and design reviews where docs and tests must stay in sync

Quick Start

Create a spec file with executable blocks and run it with specdown to see results.

Frequently Asked Questions about specdown

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn Markdown documentation into executable tests?

You can turn Markdown into executable tests by authoring specifications with shell blocks, inline assertions, and check tables, then running them with an executable spec runner to validate outputs automatically.

What is an executable specification and how does it work in Markdown?

An executable specification blends documentation with verifiable tests, allowing shell commands, inline assertions, and check tables written directly in Markdown to be executed and validated against implementation behavior.

How do I run Alloy models for design validation inside Markdown specs?

You can run Alloy models for design validation by embedding Alloy fragments directly within Markdown specifications, allowing the executable spec runner to validate both design models and implementation checks in sync.

Can I validate CLI workflows and API specs using Markdown check tables?

Yes, you can validate CLI workflows and API specs using check tables and shell adapters within Markdown, ensuring that documentation and tests remain synchronized and verifiable across implementation cycles.

Do I need a specific adapter protocol to execute shell blocks in Markdown?

No specific adapter is required to start, as the executable spec runner supports a pluggable adapter ecosystem with shell adapters, allowing you to execute shell blocks and inline assertions with minimal setup.

How do I maintain traceability between executable specs and implementation?

You maintain traceability by using frontmatter-driven workflows and traceability integration within the executable spec runner, linking Markdown checks directly to implementation and design review outputs.