Skillspec

SkillSpec

SkillSpec post-install setup and skill-authoring multiplexer for inspecting skill/repo shape with doctor, mapping multi-skill and plugin-shaped workspaces, importing existing prose skills, inspecting SkillSpec status, installing compiled workspaces with visibility planning, installing/updating/enabling/disabling router mode, installing/updating/enabling/disabling/deleting durable-executor, creating specs from observed durable execution workspaces, revising SkillSpecs, compiling reviewed skills, optional install, and value reporting.

Use the directory that contains this loaded SKILL.md as <skill_dir>. The SkillSpec contract is <skill_dir>/skill.spec.yml; do not assume the user's current working directory contains the spec.

Start the SkillSpec guide with the user's task:

skillspec run-loop <skill_dir>/skill.spec.yml --input '<user task>' --trace-dir "${PWD}/.skillspec/traces" --guide agent --json

Resume an existing guided run:

skillspec run-loop <skill_dir>/skill.spec.yml --resume <run_dir> --guide agent --json

Use the JSON current gate as internal control data. The selected route, matched rules, forbids, allowed commands, open requirements, resume command, and end proof from the CLI guide are authoritative; do not narrate the raw JSON to the user.

Keep SkillSpec mechanics in the background. Do not narrate ledger writes, raw progress commands, checkpoint rows, trace plumbing, or alignment internals as user-facing progress. Show simple intent-level updates only, such as what was assessed, what changed, what passed, and what remains blocked.

Do not run skillspec act, skillspec query, skillspec refs, or skillspec --help during normal execution. Use them only when the guide explicitly names an exact command, a blocker proves the current gate is insufficient, or the user asks to inspect internals.

For read-only diagnostic routes such as Doctor/source-shape assessment, run the diagnostic command or skillspec doctor checklist <source> --json when available, answer directly, and stop. Do not create source maps, import drafts, progress ledgers, final-response proof, or alignment summaries unless the user explicitly asks for proof.

For security assessment — what a skill could reach if executed, and a least-privilege boundary for it — use the standalone skillspec boundary commands and answer directly. This is a separate read-only tool that needs no skill.spec.yml and installs/changes nothing:

• skillspec boundary map <folder-or-url> — Structure: a tree of a skill collection (skills, resources, orphan files, cross-references). --json for the graph.
• skillspec boundary assess <folder-or-url> — Security analysis: what each skill can reach if executed, ranked by severity (critical/high/medium/low), scope-aware (a skill confined to its own directory is low risk), with documentation examples qualified rather than counted as live effects. --json for structured findings.
• skillspec boundary <skill-or-url> — the raw effect surface: what it reads, reaches, executes, plus concealment and directive findings.
• skillspec boundary gate <folder-or-url> --then '<install command>' — assess a skill/plugin before install, present tree and risk, and run the install only on approval.
• skillspec pull <folder-or-url> — assess then install across harnesses: proxy to the Claude/Codex plugin CLI for a marketplace repo, or place skill folders for any AGENTS.md/SKILL.md harness. skillspec update <source> re-pulls and shows capability drift before replacing an installed skill.
• skillspec boundary emit <skill> — a deny-by-default policy compiled from that surface.
• skillspec boundary guard install|add|mode enforce — enforce a reviewed policy against installed skills via a managed PreToolUse hook.

Both local paths and public git URLs (GitHub, GitLab, Bitbucket, self-hosted) are supported; nothing in the analyzed package is executed. See docs/boundary-guide.md.

For proof-bearing execution routes, prefer skillspec run checklist <run_dir> --stage entry|loop|exit --json when available for current-phase cues, proof requirements, repeat-until conditions, forbids, and final alignment directives. Otherwise use the run-loop guide's current gate. Record routine successful evidence with one quiet skillspec progress checkpoint ... --quiet command at natural phase boundaries. Use individual skillspec progress record only for failures, blockers, or debugging.

For imports, prefer skillspec import checklist <source-or-workspace> --stage entry|loop|exit --json when available. The generated checklist owns the shape-specific template for single SKILL.md, multi-skill folder, or plugin-shaped source; follow its package/file/block repeat loops, commands, directives, evidence requirements, activation policy, and forbids until complete or blocked. Do not review one representative package, bulk-promote scaffolds, or install generated drafts.

Missing alignment proof is not a prompt-writing task. Do not create route, obligation, elicitation, or phase proof rows after the fact to make alignment pass. If evidence was not captured when the work happened, report partial alignment and the exact missing proof instead of manufacturing progress.

If the skillspec CLI is not installed, report that this skill requires SkillSpec and ask the user to install it before continuing:

curl -fsSL https://raw.githubusercontent.com/modiqo/skillspec/main/install.sh | sh
# or, with Rust installed:
cargo install skillspec

If the user declines or installation is impossible, read <skill_dir>/skill.spec.yml directly and manually follow the same route, rule, phase, dependency, forbid, proof, and completion contract. Report that CLI guidance was unavailable and alignment proof is partial.