A workspace is a repository that contains more than oneDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt
Use this file to discover all available pages before exploring further.
SKILL.md package under a shared source root. This includes multi-skill repositories with independent skill folders, plugin-shaped repositories that carry a namespace root (skills/ directory plus harness-neutral plugin metadata such as .claude-plugin/marketplace.json, .codex-plugin/plugin.json, or .agents/plugins/marketplace.json), and entry skills that reference shared helper or wrapper packages.
The workspace flow handles all of these shapes as a unit — mapping package identity, discovering hard dependency edges from file references, building and caching generated artifacts, and installing compiled packages into harness roots while preserving the source parent layout.
When to use workspace flow
Use workspace flow when your source root contains any of the following:- Two or more
SKILL.mdfiles at any depth - A
skills/directory alongside harness-neutral plugin manifests (.claude-plugin/marketplace.json,.codex-plugin/plugin.json,.agents/plugins/marketplace.json) - Cross-skill file references that imply dependency ordering
- Skills that must be installed at mirrored source-relative paths rather than flattened folder names
Full workflow
Map the workspace
Discover all The manifest records each package’s
SKILL.md packages, detect plugin namespace roots, infer hard dependency edges from file and slash-command references, assign install slugs, and write a workspace manifest:package_id, path, kind, public_name, install_slug, and depends_on edges. The --summary flag prints wall-clock and estimated token metrics while keeping stdout compact — the full proof files are still written to disk.Validate the manifest
Check the package graph for cycles, self-dependencies, missing dependency references, duplicate public names, duplicate install slugs, and plugin packages outside their expected namespace before starting import work:Duplicate public names are reported as warnings at validation time and become errors at install time. Plugin slash-command workflow references are treated as informational; only file references that resolve across packages require
depends_on coverage.Import — generate skill.spec.yml for each package
Run fanout import for every package in dependency order. Packages in the same dependency level can be imported in parallel; unchanged packages with intact build artifacts are reused from cache:Outputs are written under a mirrored build root. A failed package does not stop other independent packages from proceeding. The command reports
built, cached, failed, skipped, and blocked counts.Import does not compile SKILL.md loaders, install skills, or refresh router indexes — it generates skill.spec.yml drafts that need review before the next step.Converge — verify the build before compiling
Verify that every package has a ready generated Converge writes
skill.spec.yml or explicit failure evidence, validate generated specs, check promotion proof hashes, and confirm that dependent packages are not blocked by unready dependencies:workspace-converge.report.md. If scaffolds or unresolved source obligations remain, it points back to import checklist --stage loop rather than reporting success — that is recoverable work, not a final-response condition.Compile — generate SKILL.md loaders
Recheck convergence, then compile each ready package’s Valid
skill.spec.yml into a generated SKILL.md loader under the mirrored build root:--target values are codex-skill and claude-skill. Dependent packages whose dependencies did not compile are blocked and reported. Compile writes workspace-compile.report.md.Install — write packages into harness roots
Preflight the compiled build, then install packages into harness skill roots. Use Remove Valid
--dry-run first to review every planned write before any files are changed:--dry-run to perform the actual install. Successful install writes workspace-install.report.md and workspace-install.manifest.json with parent/path proof.--target values are agents, codex, and claude-local. Use --all-detected to install into every detected harness root in one pass.Shape detection
skillspec workspace map detects the source shape automatically and records it in the manifest:
| Shape kind | Description |
|---|---|
single_skill | One SKILL.md package — use port-one-shot instead |
multi_skill_workspace | Multiple independent SKILL.md packages with no shared plugin root |
plugin_workspace | A skills/ namespace directory alongside plugin manifest files |
Caching
Unchanged packages with intact build artifacts are reused automatically between import runs. The cache state lives in<build-root>/.skillspec/workspace-cache.json and is keyed by package path and source content hash. The import report shows cached packages separately from built ones so you can see exactly what was reused and what was regenerated.
Install slug policy
The--install-slug-policy flag controls how install folder names are assigned:
workspace-path (default)
Derives the install slug from the source-relative path of each package. This is shape-preserving for multi-skill and plugin workspaces and is the correct choice when packages must install at predictable relative paths. Example:
skills/pdf → skills--pdf.local-name
Uses each package’s local folder name as the install slug. This is suitable only for single-package replacement installs that must retire a specific canonical folder name such as
rote-setup. Multi-skill and plugin-shaped manifests reject local-name because it flattens source-local identity.Visibility
skillspec workspace install supports --apply-visibility to set native harness visibility on installed packages and --visibility-manifest to write a reversible manifest for later restore:
--visibility-policy values:
| Policy | Behavior |
|---|---|
entry-implicit | Entry packages are implicit; shared, helper, and wrapper packages are manual-only |
all-implicit | All installed packages are implicit |
all-manual | All installed packages are manual-only |
none | No visibility changes are applied |
skillspec router index refresh after install to reapply router-managed visibility and rebuild the routing catalog.