kevinslin/schemas

Schemas

Use this skill to understand and materialize hierarchical file schemas stored under ./references/<schema>/.

Available Schemas

• tool: Dendron note hierarchy for pkg.<name> and vpkg.<name> tool documentation. See ./references/tool/schema.yaml.
• code: Specy-style code documentation tree under the selected output root, usually a $mem base root, at packages/{{module}}, including navfiles, dev/QA, reference catchalls, architecture, research, design, specs, flows, state, recipes, FAQ, vendor docs, and database docs. See ./references/code/schema.yaml.
• code-core: Reusable code documentation subtree with dev/qa, dev/obs, flow/{{flow}}, arch/{{arch}}, and API reference nodes. See ./references/code-core/schema.yaml.
• global-core: Reusable global reference and topic namespaces with ref/{{reference}} and t/{{topic}}. See ./references/global-core/schema.yaml.
• integ-proof: Integration behavior proof tree with claim, status, scenario summaries, proof-local scripts, and arbitrary raw artifacts. See ./references/integ-proof/schema.yaml.
• project: Project-level directory tree with specs/, root-level flow docs, cookbooks, and reports. See ./references/project/schema.yaml.
• specs: Agent Project Directory tree with active numbered spec directories, a root .archive for completed or superseded spec units, and per-spec artifacts, flow docs, cookbooks, milestones, integration proofs, and reports. See ./references/specs/schema.yaml.

Schema Layout

Each schema lives in its own reference directory:

references/
  <schema>/
    schema.yaml
    <template>.md.jinja
    <template>.py.jinja
    default.md.jinja

Use schema.yaml for structure and keep templates next to it. Template files may use any output extension before .jinja; for example, root.md.jinja creates Markdown content and module.py.jinja creates Python content. A node's template field selects the template basename. If template is omitted from a leaf node, use default.

Schema Fields

Use this shape:

version: 1.0
output:
  file_extension: md
variables:
  prefix: [pkg, vpkg]
  name: ["*"]
schema:
  "{{prefix}}":
    "{{name}}":
      description: root file
      template: root
      children:
        cli:
          description: command usage
          insertion_policy:
            avoid_when:
              - the information is general project context rather than CLI-specific usage
          template: cli
        docs:
          description: mounted documentation subtree
          children_from:
            - schema: code-core
              vars:
                module: "{{name}}"

• variables: Optional restrictions, defaults, and descriptions for path placeholders such as {{name}}. Omit unrestricted placeholders; callers can still pass undeclared values with --var name=value.
• output.file_extension: Append this extension to generated paths unless the caller overrides output behavior.
• schema: A tree of path segments. Segments can be literal strings or {{variable}} placeholders.
• description: Human-readable navigation help for a node. Prefer improving this before adding insertion policy.
• String node values are shorthand for description; for example dev: how to setup for development.
• insertion_policy: Optional routing hints for deciding whether new information belongs in this node. Use it only when description is not enough, such as when two nodes are easy to confuse or a common wrong insertion should be avoided. Supported keys:
  • use_when: Short phrases describing evidence that belongs in this node.
  • avoid_when: Short phrases describing evidence that should go somewhere else.
• template: Template basename in the schema directory. Omit it on a leaf node to use default. Nodes with children or mounted child schemas and no template are path-only namespace nodes.
• children: Child nodes below the current path segment.
• children_from: Mounted child schemas to add below this node. Use a scalar such as children_from: code-core for a bundled schema with no variable mapping, or a list of entries that each set exactly one of schema (a bundled ./references/<schema>/schema.yaml) or path (a schema file or directory relative to the parent schema directory). Parent variables are not inherited by default; use vars to explicitly pass rendered values into the child schema. If a vars value references a parent value that was not provided, that child var is omitted so unselected child branches can remain skipped. Child variable restrictions and defaults apply only while traversing the child tree. If a mounted child root conflicts with an explicit parent children entry, the parent entry wins for its own fields while non-conflicting child descendants remain available.
• dynamic_child: Set to true when the node represents a namespace that can grow arbitrary named children.

Commands

Run commands from the directory containing this SKILL.md, or put ./scripts on PATH to use the short schema ... form. When another sibling skill depends on schemas, read this skill first and invoke the CLI relative to that sibling skill directory, for example ../schemas/scripts/schema.py show tool.

List bundled schemas:

./scripts/schema.py list

Show a schema tree before generating files:

./scripts/schema.py show tool

Show schema descriptions as Markdown bullets:

./scripts/schema.py describe tool

Materialize a schema node:

./scripts/schema.py materialize tool \
  --out /tmp/schema-output \
  --path-style dotted \
  --var prefix=pkg \
  --var name=test \
  --include pkg.test \
  --skip-existing

Materialize another node by including its full rendered path:

./scripts/schema.py materialize tool \
  --out /tmp/schema-output \
  --path-style dotted \
  --var prefix=pkg \
  --var name=test \
  --var topic=config \
  --include pkg.test.t.config \
  --skip-existing

For directory-style schemas, pass --include using slash-separated rendered paths so literal-dot directory names still work:

./scripts/schema.py materialize specs \
  --out /tmp/specs-output \
  --path-style directory \
  --var spec_number=1 \
  --var spec_slug=example \
  --var report=security-review \
  --include specs/1-example/reports/security-review \
  --skip-existing

Use --path-style dotted for Dendron-style files such as pkg.test.cli.md; use --path-style directory for directory paths such as pkg/test/cli.md. When omitted, materialize infers path style from the include syntax or existing output-root convention: slash-separated includes imply directory, dotted includes imply dotted, and an existing output root with nested Markdown files or top-level dotted Markdown files is used as a fallback.

The schema.py materialize subcommand validates schema.yaml with Pydantic, renders path placeholders with provided declared or undeclared variables, renders each selected Jinja template, and uses Copier to initialize the output files.

Navigation Rules

• Read schema.yaml first when deciding which files to materialize.
• Use description as the primary guide for choosing where new information belongs.
• Use insertion_policy only as a tie-breaker or guardrail when the description alone is ambiguous. Do not duplicate section headings or restate the description; templates already define document sections.
• Materialize only explicitly requested nodes by passing --include <full.rendered.path>.
• Pass --path-style from the caller's directive, selected $mem base config, or observed output-root convention. Do not define path style inside schema.yaml.
• Use --skip-existing when initializing into a directory that may already contain hand-edited files.
• Treat dynamic_child: true as an instruction that more children may be added later; do not invent dynamic children without user intent.
• Treat children_from as schema composition, not inheritance. Plumb parent values into a mounted child only through that mount's vars mapping.
• Keep template names stable and update the schema before adding new template files.