CLI

v0.3.0 ships a real skillweave CLI that loads a pipeline from YAML, resolves its skills from the registry, and drives it through the orchestrator. Run it via the bin or npm run cli:

npm run cli -- <command> [args]   # or: npx skillweave <command> [args]

Commands

Command	What it does
doctor	One-command readiness report (Node · judge provider · skills · registry)
run <pipeline.yaml> [--doc <path>] [--inject <mode>]	Load + execute a pipeline
validate <pipeline.yaml>	Structural + reference check, no execution
test <skill> [--input <state.json>]	Run a single skill in isolation
list [skills|pipelines]	List registered skills (or pipeline files)
trace [last]	Print the most recent NDJSON trace
new pipeline|skill <name>	Scaffold a starter file
health	Composite 0–100 health score + grade (SigMap OBSERVE adapter)
sigmap context|cost|health	SigMap adapter access (CONTEXT · COST · OBSERVE)
providers	Provider/model capability table (tier · structured-output · cost)
neutral <file>	Neutral Skill Language check (exit 1 on model-specific syntax)
check-schemas	Validate the schema registry + skill pins + additive-only rule
check-permissions	Audit each skill's capabilities against the security policy
verify [--input <file>] [--context <dir>]	Run the sigmap-verify pipeline and print the verdict
publish <skill>	Grade a skill and publish it to the registry
install <skill>	Look up a published skill in the registry
registry [list]	List published skills grouped by tier
memory [pipeline]	Report the learning trend + failure patterns from past runs
visualise <pipeline.yaml> [--mermaid]	Render a pipeline as an ASCII or Mermaid diagram

The npm start entrypoint still runs the built-in document-grounding chain directly.

doctor

The newcomer's first command: a one-line-per-check readiness report. It names your Node version, the active judge provider (or the offline heuristic — no API key needed), how many skills are registered, and whether a registry/traces exist, then confirms you can run right now. Read-only; always exits 0.

npm run cli -- doctor
# skillweave v1.1.0 — doctor
#   ✓ Node.js         v20.11.0
#   ✓ Judge provider  offline heuristic — no API key needed
#   ✓ Skills          5 registered
#   • Registry        none yet — try: skillweave publish <skill>
#   • Artifacts       no runs yet — try: skillweave run
# ✓ ready — you can run `skillweave run` now (offline by default).

The same report is available in-process as runDoctor() from the package entry. Mistyped a command or skill name? The CLI suggests the closest match — skillweave verfy → did you mean 'verify'?.

run

Loads a pipeline YAML, resolves each step's skill, and executes via the orchestrator.

npm run cli -- run pipelines/document-grounding.pipeline.yaml
npm run cli -- run pipelines/document-grounding.pipeline.yaml --doc ./notes/q3.md
npm run cli -- run pipelines/document-grounding.pipeline.yaml --inject hallucination

Flag	Effect
--doc <path>	Run on a document file instead of the built-in sample
--inject <mode>	Drive a reliability demo: lowconf · hallucination · persistent · coverage

Exit 0 on STATUS: SUCCESS, 1 on STATUS: HALTED.

validate

Checks a pipeline YAML without executing it: required top-level fields, a non-empty step list, every skill resolvable in the registry, and confidence_threshold / retries in range. A mismatched declared execution_class is a warning.

npm run cli -- validate pipelines/document-grounding.pipeline.yaml
# ✓ pipelines/document-grounding.pipeline.yaml: valid

Exits non-zero when there are errors, printing one line per issue.

test

Runs a single skill in isolation — executes run() once, applies its STATE writes, and runs its assertions. Supply input state as JSON with --input:

npm run cli -- test parse-input
npm run cli -- test extract-highlights --input ./fixtures/blocks.json

Exit 0 if assertions pass, 1 if any fail.

list / trace

npm run cli -- list             # registered skills (name · class · does)
npm run cli -- list pipelines   # pipeline YAML files
npm run cli -- trace            # the latest run's NDJSON trace, row by row

new

Scaffolds a starter file (refuses to overwrite an existing one):

npm run cli -- new pipeline my-flow   # → pipelines/my-flow.pipeline.yaml
npm run cli -- new skill my-skill     # → src/skills/my-skill.ts (then register it)

Pipeline YAML

run and validate operate on a .pipeline.yaml:

name: document-grounding
version: 0.3.0
domain: documents
pipeline:
  - skill: parse-input
    execution_class: deterministic
  - skill: extract-highlights
    execution_class: probabilistic
    confidence_threshold: 0.80   # overrides the skill default for this step
    retries: 2

Each skill must be registered (see skillweave list). Per-step confidence_threshold and retries override the skill's defaults for that step only — the registered skill is never mutated. A step may also declare a memory: block (reads / writes) to scope what a skill may read from and write to the MEMORY store.

A pipeline may also declare a trigger: and events: block — how it is activated, and which observability signals it routes:

trigger:
  type: manual              # manual | cron | webhook | pipeline_completion | ...
events:
  - on: skill_failed        # named occurrence the orchestrator emits
    emit: failure           # info | warning | alert | failure
    notify: [trace-log, webhook]
    continue: false         # halt after this event

Both blocks are parsed and validated by validate. See the Triggers & events guide.

health

Computes a composite 0–100 health score and grade (SigMap scale: A≥90 · B≥75 · C≥60 · D<60) from the NDJSON metric stream — success rate, judge-pass rate, and low-retry rate across recent runs. The grade also prints as a footer after every run / npm start.

npm run cli -- health
# health: A (100/100)
#   runs            : 1
#   success rate    : 100%
#   judge pass rate : 100%
#   low-retry rate  : 100%

sigmap

Direct access to the SigMap adapters — wrappers over SigMap's local artifacts (no shell spawn).

npm run cli -- sigmap context --query "auth flow"      # prints .context/query-context.md if present
npm run cli -- sigmap cost --suggest-tool "refactor auth security"   # → tier: powerful
npm run cli -- sigmap cost                              # total cost across traces
npm run cli -- sigmap health                            # alias of `health`

providers

Prints the provider/model capability table loaded from provider-profiles/*.profile.yaml (see the provider layer).

npm run cli -- providers
# anthropic
#   claude-opus-4-8    powerful  structured     $0.005/$0.025 per 1k
#   ...

neutral

Checks a file against the Neutral Skill Language Standard — skill instructions must run on any LLM, so they may not name a model/vendor, use thinking-block / XML syntax, or assume a context-window size. Exits non-zero on violations.

npm run cli -- neutral docs/my-skill.md
# ✓ docs/my-skill.md: model-neutral

check-schemas

Validates the schema registry: every schemas/registry/<name>@<version>.json parses (and its $id matches the filename), every skill input_schema / output_schema pin resolves, and the additive-only rule holds across consecutive versions within each major. Exits non-zero on a breaking change within a major.

npm run cli -- check-schemas
#   content-block 1.0→1.1: +lang
# ✓ 8 schemas valid · 7 pins resolve · additive-only holds

check-permissions

Audits the security model: every registered skill's declared capabilities are checked against DEFAULT_POLICY (default-deny). A skill that requests a capability the policy does not grant — or one outside the known vocabulary — fails the gate. Exits non-zero on any violation.

npm run cli -- check-permissions
#   load-context         [fs:read]
#   parse-input          [pure]
#   validate-coverage    [pure]
#   extract-highlights   [pure]
#   memory-update        [fs:read, fs:write]
# ✓ 5 skills within policy (granted: fs:read, fs:write)

verify

Runs the sigmap-verify pipeline — SkillWeave's verify flow for SigMap. With no --input, the load-context skill sources the input from SigMap's CONTEXT artifact (.context/query-context.md); --context <dir> points it at a different context directory. Prints a structured verdict and exits non-zero on a halt.

npm run cli -- verify --input ./notes/q3.md
# sigmap-verify: success
#   grounded   : true (judge 1)
#   coverage   : 1
#   highlights : 2
#   health     : C (72/100)

Flag	Effect
--input <file>	Verify a file instead of SigMap's CONTEXT artifact
--context <dir>	Read the CONTEXT artifact from <dir> instead of .context/

The same run is available in-process as runSigMapVerify() — see the SigMap verify guide.

publish / install / registry

The skill registry — a tiered, quality-gated, local-first catalog of published skills. publish runs the 9-point quality gate, assigns a trust tier (verified / community / experimental), and writes the entry to .registry/skills.json; a skill below the experimental floor is refused. install looks an entry up; registry lists the catalog by tier.

npm run cli -- publish extract-highlights
#   ✓ name is kebab-case
#   ... (9 checks)
# ✓ published extract-highlights — verified (9/9 · reputation 100)

npm run cli -- registry
# verified
#   extract-highlights   9/9   reputation 100

npm run cli -- install extract-highlights
# extract-highlights@1.0.0 — verified (9/9 · reputation 100)

publish exits 1 when a skill is rejected (below the experimental floor); install exits 1 when the skill is not in the registry. The same surface is available in-process via gradeSkill / publishSkill / installSkill / listRegistry from the package entry.

memory

Reports what the MEMORY primitive has learned from past runs — the score trend, pass rate, and any recurring failure patterns with recommendations, per pipeline (or a single one when named). Read-only; exits 0.

npm run cli -- memory
# document-grounding
#   runs        : 10
#   avg score   : 1
#   pass rate   : 100%
#   failures    : 0
#   • healthy — no recurring failure patterns detected

The same data is available in-process via MemoryStore (record / recall / stats) and failurePatterns / recommend from the package entry.

visualise

Renders a pipeline as a text diagram — an ASCII flow by default, or a Mermaid flowchart with --mermaid (paste into any Mermaid renderer). Part of the OBSERVE layer.

npm run cli -- visualise pipelines/document-grounding.pipeline.yaml
# document-grounding v0.3.0  (documents)
# trigger: manual
# parse-input  →  validate-coverage  →  extract-highlights  →  memory-update
# events:
#   low_confidence_detected → warning [trace-log]
#   skill_failed → failure [trace-log, webhook] (halt)

npm run cli -- visualise pipelines/document-grounding.pipeline.yaml --mermaid
# flowchart TD
#   ...

Exits 0 on success, 2 when no pipeline file is given. Available in-process as visualise().

Provider selection

The boundary judge picks a provider from environment variables — see the provider layer guide:

ANTHROPIC_API_KEY=... npm run cli -- run <pipeline>   # or GEMINI_API_KEY / OPENAI_API_KEY
JUDGE_PROVIDER=gemini npm run cli -- run <pipeline>    # force a provider

Other scripts

Command	What it does
npm start [-- --doc <path>] [-- --inject <mode>]	Run the built-in document-grounding chain
npm test	node:test suite (137 tests)
npm run bench	Reliability benchmark (writes metrics to version.json with --save)
npm run typecheck	tsc --noEmit

Artifacts

Path	Written by	Contents
traces/<run-id>.ndjson	base-log	One metric line per attempt (SigMap usage.ndjson-compatible)
traces/checkpoints/	base-io	A STATE snapshot after each skill
.context/skillweave-memory.ndjson	memory-update	The local learning log (score trend across runs)

All three are gitignored.

Exit codes

Code	Meaning
0	Success (chain completed / valid / assertions passed)
1	Halt, validation errors, or assertion failure
2	Bad CLI usage (missing/unknown argument)