skillspec workspace — Multi-Skill Pipeline Commands

skillspec workspace is the authoring pipeline for multi-skill repositories and plugin-shaped workspaces. The pipeline advances through six ordered stages: map → validate → import → converge → compile → install. Each stage must succeed before the next can proceed.

`workspace map`

Discovers packages in a multi-skill source root, assigns deterministic install slugs, detects plugin namespaces, infers hard dependency edges from file references, and writes a skillspec.workspace.yml manifest.

skillspec workspace map <source-root> \
  --out <skillspec.workspace.yml> \
  [--install-slug-policy workspace-path|local-name] \
  [--summary] \
  [--json]

Flag	Description
`<source-root>`	Root directory containing SKILL.md packages.
`--out <path>`	Output path for the `skillspec.workspace.yml` manifest.
`--install-slug-policy workspace-path\|local-name`	Slug policy. `workspace-path` (default) is shape-preserving for multi-skill and plugin workspaces. `local-name` is only for single-package replacement installs that must retire canonical existing folders.
`--summary`	Print wall-clock and estimated token metrics while preserving full proof files.
`--json`	Emit JSON report.

Plugin slash-command links are workflow references, not hard dependency edges. This is not router indexing.

skillspec workspace map ./skills \
  --out ./build/skillspec.workspace.yml \
  --summary

`workspace validate`

Validates a workspace manifest’s package graph before fanout import. Checks source root, package paths, exactly one SKILL.md per package, dependency references, self-dependencies, cycles, install slug uniqueness, and uncovered hard cross-package references.

skillspec workspace validate <skillspec.workspace.yml> [--summary] [--json]

Duplicate public names are warnings until install planning. Plugin slash-command workflow references may cross packages without depends_on; file references still require dependency coverage. Exits non-zero when validation fails.

skillspec workspace validate ./build/skillspec.workspace.yml --summary

`workspace import`

Runs fanout import for every package in a validated workspace graph. Dependency-ready packages at the same graph level may run in parallel; unchanged packages with intact artifacts are reused from a workspace cache and reported as cached.

skillspec workspace import <skillspec.workspace.yml> \
  --out <build-root> \
  [--summary] \
  [--json]

Flag	Description
`--out <build-root>`	Output build root directory.
`--summary`	Keep stdout compact; report preserved artifact tokens plus cache hits/misses.
`--json`	Emit JSON report.

The command writes outputs under one mirrored build root, preserves successful package outputs when another package fails, and reports built, cached, failed, skipped, and blocked packages. It does not compile, install, or refresh router indexes. Exits non-zero on failures.

skillspec workspace import ./build/skillspec.workspace.yml \
  --out ./workspace-build \
  --summary

`workspace converge`

Verifies the generated workspace build against the manifest before compile/install. Checks that every package has a ready skill.spec.yml or explicit failure evidence, validates generated specs, verifies workspace promotion proof hashes, and writes workspace-converge.report.md.

skillspec workspace converge <skillspec.workspace.yml> \
  --build-root <build-root> \
  [--summary] \
  [--json]

Flag	Description
`--build-root <dir>`	Build root written by `workspace import`.
`--summary`	Print compact readiness counts plus wall-clock/token metrics.
`--json`	Emit JSON report.

Blockers: boolean-only promotion proof without source-obligation coverage; unresolved or targetless source obligations; dependents whose dependencies are not ready. If the build root is empty, next points to workspace import. If scaffolds or missing promotion proof remain, next points to import checklist --stage loop. Exits non-zero on failure.

skillspec workspace converge ./build/skillspec.workspace.yml \
  --build-root ./workspace-build \
  --summary

`workspace compile`

Rechecks convergence, compiles ready package specs into generated SKILL.md loaders under the mirrored build root, blocks dependents whose dependencies did not compile, and writes workspace-compile.report.md.

skillspec workspace compile <skillspec.workspace.yml> \
  --build-root <build-root> \
  --target <codex-skill|claude-skill> \
  [--summary] \
  [--json]

Flag	Description
`--build-root <dir>`	Build root written by `workspace import`.
`--target codex-skill\|claude-skill`	Compile target for generated SKILL.md loaders.
`--summary`	Print compact compile counts plus wall-clock/token metrics.
`--json`	Emit JSON report.

Does not install skills or refresh router indexes. Exits non-zero when compile fails for one or more packages.

skillspec workspace compile ./build/skillspec.workspace.yml \
  --build-root ./workspace-build \
  --target codex-skill \
  --summary

`workspace install`

Preflights a compiled workspace build and installs packages into harness roots.

skillspec workspace install <skillspec.workspace.yml> \
  --build-root <build-root> \
  [--target <agents|codex|claude-local>] \
  [--all-detected] \
  [--dry-run] \
  [--retire-existing] \
  [--install-slug-policy workspace-path|local-name] \
  [--visibility-policy entry-implicit|all-implicit|all-manual|none] \
  [--apply-visibility] \
  [--visibility-manifest <path>] \
  [--summary] \
  [--json]

Flag	Description
`--build-root <dir>`	Build root written by `workspace import`.
`--target agents\|codex\|claude-local`	Target harness(es). Repeatable.
`--all-detected`	Install to all detected harness roots.
`--dry-run`	Show every planned write and intended visibility without writing files.
`--retire-existing`	Back up existing skills under `~/.skillspec/backups/retired-skills` and remove them before installing.
`--install-slug-policy workspace-path\|local-name`	Override the manifest’s slug policy. Multi-skill and plugin-shaped manifests reject `local-name`.
`--visibility-policy entry-implicit\|all-implicit\|all-manual\|none`	Visibility policy to apply when `--apply-visibility` is set. Default: entry packages are implicit; shared/helper/wrapper packages are manual-only.
`--apply-visibility`	Apply native harness visibility controls during install.
`--visibility-manifest <path>`	Path for the reversible visibility manifest written during install.
`--summary`	Print compact install counts plus wall-clock/token metrics.
`--json`	Emit JSON report.

Multi-skill and plugin-shaped manifests hard-preserve the source parent shape. The install copies the original parent folder (omitting the source skill package subtree) and writes compiled packages back at the same relative paths. Flattened per-package folder names are rejected for these shapes.

Always run with --dry-run first to review every planned write and visibility change before performing an actual install.

After actual install, if the source root is inside a local Git checkout, the next steps recommend opening a PR with the generated contracts and proof artifacts only after restarting the harness and interacting with the installed SkillSpec-backed skills through the agent.

# Dry run first
skillspec workspace install ./build/skillspec.workspace.yml \
  --build-root ./workspace-build \
  --target codex \
  --retire-existing \
  --dry-run \
  --summary

# Actual install after reviewing the dry-run output
skillspec workspace install ./build/skillspec.workspace.yml \
  --build-root ./workspace-build \
  --target codex \
  --retire-existing \
  --summary

Grammar subcommands

These commands teach the embedded SkillSpec grammar and coverage workflow. Run grammar sensemake --view porting before importing or revising a spec so the harness does not infer grammar from memory.

Subcommand	Synopsis	Description
`grammar sensemake`	`skillspec grammar sensemake [--view index\|summary\|porting\|full] [--json]`	Teaches the embedded grammar artifact progressively. `porting` view is optimized for import and revision workflows.
`grammar checklist`	`skillspec grammar checklist [--for import-skill] [--json]`	Shows the embedded coverage checklist for a semantic porting or review workflow. Currently only `import-skill` is supported; defaults to `import-skill`.
`grammar schema`	`skillspec grammar schema [--json]`	Prints or summarizes the embedded JSON Schema used by grammar-aware harnesses and reviewers.

# Load grammar context before beginning a workspace import
skillspec grammar sensemake --view porting

# Get the import-skill coverage checklist
skillspec grammar checklist --for import-skill --json

Source subcommands

These subcommands build and query source maps for individual skill sources, useful before and during import.

Subcommand	Synopsis	Description
`source stage`	`skillspec source stage <github-uri> --out <dir> [--no-detect-candidates] [--json]`	Stage a public GitHub repo URL, tree URL, blob-style folder URL, or owner/repo shorthand for candidate discovery or explicit staging.
`source map`	`skillspec source map <path-or-github-uri> --out <dir> [--json]`	Build `source-map.json` and `source-map.md` from a prose skill file, folder, or public GitHub URI.
`source query`	`skillspec source query <source-map.json> <handle> [--view index\|summary\|full] [--json]`	Retrieve source-map collections or exact nodes. Common handles: `files`, `nodes`, `dependencies`, `code`, `coverage`, `frontmatter:<file>`, `heading:<file>.<slug>`, `code:<file>.<n>`.
`source lens`	`skillspec source lens <source-map.json> [--cursor <n>] [--limit <n>] [--json]`	Show deterministic progressive review units. Each unit has a countdown, source hash, line range, preview, classifications, and suggested constructs.
`source coverage`	`skillspec source coverage <source-map.json> [--json]`	Summarize mapped nodes, review-required classifications, and stale counts.
`source stale`	`skillspec source stale <source-map.json> [--root <path>] [--json]`	Recompute file hashes and exit non-zero when mapped source files changed or disappeared. Run before import, proof, or install.

skillspec doctor <path> — Assess follow-through risk and confirm workspace shape before mapping.
skillspec import checklist <manifest> --stage <stage> — Generate the concrete import checklist for each pipeline stage.
skillspec router index refresh — Refresh the router index after a workspace install.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec workspace — Multi-Skill Pipeline Commands

`workspace map`

`workspace validate`

`workspace import`

`workspace converge`

`workspace compile`

`workspace install`

Grammar subcommands

Source subcommands

​workspace map

​workspace validate

​workspace import

​workspace converge

​workspace compile

​workspace install

​Grammar subcommands

​Source subcommands

​Related commands

`workspace map`

`workspace validate`

`workspace import`

`workspace converge`

`workspace compile`

`workspace install`

Grammar subcommands

Source subcommands

Related commands