Learned skills and synthesis

Knowl represents reusable procedure knowledge in two forms: a durable skill atom for retrieval, and an optional file-backed package for inspected execution.

File-backed skills

A package lives below the project database directory:

.knowl/skills/<name>/
├── SKILL.md
├── skill.json
└── optional scripts and support files

Create and inspect a package before running it:

knowl skill create run_app \
  --purpose "Start the app locally" \
  --markdown "# Run App" \
  --file "run.mjs=console.log('run-app')" \
  --script run.mjs

knowl skill list
knowl skill read run_app
knowl skill run run_app

Package names, file paths, and entrypoint paths are validated to stay within the package. Entrypoints can invoke a trusted local script or shell command and run without a sandbox. autoRun: false blocks execution. When a declared primary entrypoint fails, a declared fallback entrypoint may run. Knowl records usage and result statistics so operators can inspect how the package behaved; path validation is not a security boundary for untrusted script content.

Deterministic synthesis

Synthesis builds one scoped architecture item from existing atoms without calling an AI provider:

knowl synthesize --scope storage

The current scope is an exact tag, not a filesystem path. Eligible sources are active, fresh, non-state, and not themselves synthesized. A run requires at least two sources, uses at most eight, and takes at most 500 content characters from each. It creates or refreshes one architecture item and replaces its derived evidence.

Synthesis does not read session namespaces or workspace peers and does not create a knowledge commit. Use knowl_synthesize only for an explicit scope; it is not part of normal write reconciliation.