| name | softschema |
| description | Validate and structure Markdown/YAML artifacts with frontmatter contracts. Mix prose context with machine-readable values without forcing the whole document into a hard schema. Use when working with soft schemas, frontmatter validation, mixed prose-and-data files, agent pipelines that produce or consume Markdown artifacts, or running the `softschema` CLI. |
| allowed-tools | ["Bash(softschema:*)"] |
softschema Skill
softschema adds and validates structure for Markdown/YAML artifacts that mix prose
context with machine-readable values.
This skill is a routing layer.
The CLI documents itself, so load only the command output you actually need.
When to Use
A file mixes prose (notes, rationale, summaries) with values that code or a later agent
step needs to read reliably, and those values should be typed or validated without
forcing the rest of the document into a hard schema.
Pick One Runner First
Pick one command prefix, then use it for every command in this skill.
In examples, $SS ... means “run the selected prefix with these arguments.”
- If
softschema --version works, use SS='softschema'.
- Else if
uvx --version works, use SS='uvx softschema@latest'.
- Else if
npx --version works, use SS='npx softschema@latest'.
- Else install uv (
curl -LsSf https://astral.sh/uv/install.sh | sh or
brew install uv) or Node (brew install node), then retry.
The unpinned @latest is a deliberate repo policy, not an oversight: installs resolve
through a release-age cool-off gate (see $SS docs installation), which is this
project’s supply-chain control in place of a pinned version.
$SS doctor reports the installed version, available runners, and recommended command
prefix.
Bootstrap
Each command prints material the agent should read and follow:
$SS --help
$SS skill --brief
$SS docs guide
$SS docs spec
$SS docs example-artifact
$SS docs --list
Operating Brief
Use soft schemas when humans or agents write Markdown/YAML artifacts and tools need to
consume some values reliably.
- YAML/frontmatter is authoritative for any consumed value.
Do not parse Markdown body prose or tables for structured fields.
- The
softschema: block is the self-description quartet: contract (the payload
contract ID), schema (relative path to the compiled schema), envelope (the payload
key), status (strictness).
A fully self-describing artifact validates with $SS validate doc.md, no flags.
- Promote a value into YAML only when something consumes it; leave exploratory or
judgment-heavy content as prose.
- Read
$SS docs guide for the mental model.
- Read
$SS docs spec for the exact artifact format.
- Inspect
$SS docs example and $SS docs example-artifact for the copyable movie
example; $SS docs example-schema prints its compiled schema.
- Validate at the boundary with
$SS validate: no flags for a self-describing artifact;
--schema to override with a compiled schema; --model for a Pydantic/Zod model
(imports and runs local code — trusted models only; --schema is the safe path for
untrusted input). Run $SS validate --help for exact syntax.
- Keep examples copyable; do not scaffold or mutate a target project unless the user
explicitly asks for that workflow.
Install
softschema ships two interchangeable implementations with the same CLI surface; pick the
runtime you already have.
Use a zero-install runner:
uvx softschema@latest --help
uv tool install softschema
npx softschema@latest --help
Both expose the same commands and flags and validate against the same canonical schema;
the only difference is whether models are written as Pydantic or Zod.
Self-Install (Optional)
Run once per project to install discoverable mirrors of this skill, so any agent working
in the repo finds it natively:
$SS skill --install
The mirrors carry a DO NOT EDIT marker.
Re-run softschema skill --install to refresh after upgrading.
