SKILL.mdinto your agent's skills folder.Writing testable docs
DocuSOR can test your repository's own Markdown files, such as README.md, runbooks, and onboarding guides, against your running app. You keep writing normal prose. Wherever you state a checkable fact, write it as a short claim, and DocuSOR reports whether each claim is true.
There is nothing to install and no new syntax: a claim is a plain sentence with the concrete values in backticks.
How it works
- Click Test a doc on the repository page and pick a file, or have your agent call
check_docwith the repository and the file's path. - DocuSOR runs your app in an isolated sandbox at the latest commit.
- Each claim it recognizes is checked against the running app.
- You get a pass or fail for every claim, plus a warning for each line that looked like a claim but couldn't be understood.
Rules for writing claims
- Put values in backticks. Paths, URLs, ports, status codes, commands, file names, and service names go in backticks: "
GET /healthreturns200". - One claim per line. Bullets work well. List markers, headings, and bold or italic markers are ignored.
- Start the line with the claim. "listens on port
8080" works. "The API listens on port8080" does not. - No trailing punctuation. "
GET /healthreturns200" works. Adding a period at the end makes it unrecognized. - Prose is left alone. Lines with no backticks and no claim keywords are treated as documentation. Code blocks and HTML comments are skipped.
- Unrecognized claims are warnings. A line with backticks or claim keywords that doesn't match a claim below is reported as a warning. It never counts as passing and never fails the test.
What you can claim
Alternative wordings are in parentheses.
Endpoints
Write the request as GET /path, or just /path (defaults to GET). Paths are sent to your running app. Full URLs are used as written.
GET /healthreturns200(responds with, gives)GET /healthresponds (is ok, is reachable, works)/healthresponds within2s(or200ms)GET /usersbody contains"id"/apiheaderContent-Typeisapplication/json(contains, equals)/statusjson$.okistrue(equals)/adminrequires authentication (requires auth, is protected)
Files
- ships a
Dockerfile(has, includes, provides) package.jsonexists- has a
src/directory (folder, dir) package.jsonis valid JSONREADME.mdcontainsGetting Started.envis absent
Services and ports
- the
dbservice is running (container) - the
dbservice is healthy - listens on port
8080(port8080, port8080is open) - port
9000is closed - redis responds (is reachable, pings)
Commands and tools
npm testsucceedsnodeis installed (is available, is on the path)
Environment and data
DATABASE_URLis set- migrations are applied
- the working tree is clean
Networking
example.comresolves
Combining and negating claims
- Negate with "does not", "doesn't", "no longer", or "never":
/admindoes not respond - Combine with "and" or commas. Each part is checked separately: the
dbservice is running and healthy
Example
## Running the service
Start the stack with Docker Compose, then confirm:
- listens on port `8080`
- `GET /health` returns `200`
- `/health` responds within `500ms`
- the `db` service is running and healthy
- migrations are applied
- ships a `Dockerfile`What the sandbox can run
- With a Compose file, DocuSOR starts your stack before checking claims, so endpoint, port, and service claims run against real services.
- Without a Compose file, including Dockerfile-only repositories, your app is not started. File, command, tool, and environment claims still work. Endpoint and service claims will fail.
Choosing which docs to test
Any .md or .mdx file in the repository can be tested (dependency and build folders such as node_modules and dist are excluded). To list your most important docs first in the picker, add .docusor/docs.json at the repository root:
{ "docs": ["README.md", "docs/runbook.md"] }Cost and status
- Testing a doc from the dashboard is free.
- An agent's
check_docuses one credit, and only if at least one claim runs. - A doc test never changes your repository's "Validated" status.
Tips
- Prefer specific claims. "
GET /healthreturns200" proves more than "GET /healthresponds". - Write values exactly as they are: real port numbers, paths relative to the repository root, and full request lines like
POST /login. - Keep inline code out of prose lines you don't want checked, or expect a warning for them.
