Documentation
Understand Skill Capsules, install SkillRun, package an executable Agent Skill, then share and mount it through the Router when needed.
Install SkillRun
Normal users do not need Rust. The latest release publishes native binaries for macOS arm64/x64, Linux arm64/x64, and Windows x64, plus installer scripts and sha256.sum.
macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/iiwish/skillrun/releases/latest/download/skillrun-installer.sh | sh skillrun --version
Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/iiwish/skillrun/releases/latest/download/skillrun-installer.ps1 | iex" skillrun --version
Manual downloads live on the GitHub Release page. Use sha256.sum to verify archives. Rust/cargo is only required when developing SkillRun from source.
Quickstart
Five-minute local lifecycle, then a shared catalog URL
Start with one local Runtime Capsule so the lifecycle is concrete. Then use Team Library to inspect a shared catalog URL before anyone confirms a local .skr install.
- 01 Create a capsule from SOP + action.
- 02 Generate and check the Manifest before packaging.
- 03 Package .skr for distribution.
- 04 Review a shared catalog URL in Team Library before install.
- 05 Import a local artifact into local inventory.
- 06 Enable exposure only after review.
- 07 Mount the local Router into the MCP client.
- 08 Run the capability and inspect run evidence.
Author a runnable capsule
skillrun init refund --python --output tmp/quickstart skillrun manifest --cwd tmp/quickstart/refund skillrun check --cwd tmp/quickstart/refund skillrun validate --cwd tmp/quickstart/refund skillrun pack --cwd tmp/quickstart/refund
Consume it locally
skillrun import <package.skr> --id refund --json skillrun consumer inventory --json skillrun switchboard enable refund skillrun consumer exposure --json
Mount the Router
skillrun router status --json skillrun mount plan --client claude-desktop --json skillrun mount apply --client claude-desktop --json
At the end, the MCP client talks to skillrun router serve --mcp and every execution leaves local run evidence. The .skr remains the distribution artifact; Router exposure remains local and explicit. A shared catalog URL is only a read-only review surface until the user chooses a local catalog/package path for install apply.
Team Library route
Team catalog inspect, local/remote read-only status, install plan, and guarded local install apply are available through v0.6.8 for Desktop Team Library. Team distribution is not a public marketplace. Remote catalog URLs are read-only metadata sources for inspect, status, and install plan. Core verifies checksums and imports only from local catalog/package paths. Enable and mount remain explicit user choices. No downloader, dependency installation, action execution, MCP server start, trust decision, or sandbox promise is implied by catalog metadata.
Review the Desktop alpha pathSOP to Capability
SkillRun treats SOP as the source of truth for Agent capabilities.
Context Skill = SKILL.md plus optional references, scripts, templates, and examples. It is loaded by Agent terminals such as Codex or Claude Code. SkillRun does not execute it, does not expose it as an MCP tool, and does not infer actions from Markdown.
Runtime Capsule = SOP plus action, schema, examples, permissions, and Manifest. It can be inspected, checked, tested, run, packaged, imported, and optionally exposed through the SkillRun Router as MCP.
No Manifest contract, no execution. The CLI owns lifecycle contracts for both delivery paths. Desktop should visualize and confirm CLI plans; it should not invent install paths, copy files directly, or bypass rollback semantics.
Project Positioning
SkillRun is a packaging, inspection, and runtime layer for SOP-backed Agent capabilities. It is not MCP-first: MCP is one invocation surface for Runtime Capsules, not the product identity.
Context Skills teach an Agent a workflow. Runtime Capsules bind SOPs, schemas, preflights, structured envelopes, artifacts, and run evidence to executable actions. MCP exposes those capsules to compatible clients when needed.
SkillRun does not compete in the 'expose a function as a tool' space. It solves a different problem: when an Agent invokes real work, the SOP, input/output structures, boundaries, failure recovery, artifacts, and audit evidence must travel with the capability.
Runtime Capsule = SOP + action code + schema + examples + permissions + Manifest
Trust Model
SkillRun provides a manifest-bound execution and inspection layer, not an OS sandbox. It reduces the risk of Agents blindly calling actions, but running third-party actions still means executing third-party code.
Guardrails in SkillRun mean Manifest contracts, input/output schemas, preflight checks, structured envelopes, artifact containment, run evidence, and Consumer Mode static checks.
Current Trust Boundaries (v0.6.8):
What is not promised:
Agent Bootstrap Prompt
Embed this prompt so an Agent distinguishes Context Skills from Runtime Capsules before invoking anything.
[SKILLRUN BOOTSTRAP] We use SkillRun (https://github.com/iiwish/skillrun) to manage Agent capabilities with explicit boundaries. 1. First classify the artifact: - Context Skill: SKILL.md plus references/scripts/templates; load/read it, but do not execute it through SkillRun. - Runtime Capsule: SKILL.md plus action, schema, examples, permissions, and Manifest; inspect/check/test before use. 2. Read the repository README and relevant docs before installing or invoking anything. 3. Before using any Runtime Capsule, read its `SKILL.md`, run `skillrun inspect` and `skillrun check` when local access exists, and respect preflight boundaries. 4. Use structured output/error envelopes as business results. Treat stdout/stderr as logs only. 5. MCP is an optional invocation surface for Runtime Capsules, not the definition of SkillRun.