SkillRun
English

核心文档

理解 Skill Capsule，安装 SkillRun，打包可执行 Agent Skill，并在需要时通过 Router 分享和挂载。

安装 SkillRun

普通用户不需要 Rust。最新 release 已提供 macOS arm64/x64、Linux arm64/x64、Windows x64 原生二进制，同时提供 installer 脚本和 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

手动下载请使用 GitHub Release 页面，按平台选择 archive，并用 sha256.sum 做 checksum 校验。只有从源码开发 SkillRun 时才需要 Rust/cargo。

Quickstart

5 分钟本地 lifecycle，然后进入共享 catalog URL

先用一个本地 Runtime Capsule 把 lifecycle 跑实，再用 Team Library 复核共享 catalog URL；安装仍然要回到用户确认过的本地 .skr package。

  1. 01 从 SOP + action 创建 capsule。
  2. 02 先生成并检查 Manifest，再打包。
  3. 03 把 .skr 作为分发 artifact。
  4. 04 先在 Team Library 复核共享 catalog URL。
  5. 05 把本地 artifact 导入本机 inventory。
  6. 06 复核后才显式启用暴露。
  7. 07 把本地 Router 挂载到 MCP client。
  8. 08 运行能力，并检查 run evidence。

创建可运行 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

在本机消费

skillrun import <package.skr> --id refund --json
skillrun consumer inventory --json
skillrun switchboard enable refund
skillrun consumer exposure --json

挂载 Router

skillrun router status --json
skillrun mount plan --client claude-desktop --json
skillrun mount apply --client claude-desktop --json

最后，MCP client 连接的是 skillrun router serve --mcp，每次执行都会留下本地 run evidence。.skr 仍只是分发 artifact；Router 暴露仍是本地、显式、可审查的动作。共享 catalog URL 只是只读复核入口，直到用户选择本地 catalog/package 路径执行 install apply。

Team Library 路线

到 v0.6.8，Desktop Team Library 已支持本地/远程只读 catalog inspect、status、install plan，以及 guarded local install apply。它是团队分发路径，不是 Public Marketplace。 远程 catalog URL 只作为 inspect、status 和 install plan 的只读 metadata 来源。 Core 只从本地 catalog/package 路径做 checksum 校验和 registry import。 enable 和 mount 仍由用户显式确认。 catalog metadata 不意味着 downloader、依赖安装、action 执行、MCP server 启动、trust 判断或 sandbox 承诺。

查看 Desktop alpha 路径

从 SOP 到能力

SkillRun 把 SOP 作为 Agent 能力的 source of truth。

Context Skill = SKILL.md 加可选 references、scripts、templates、examples。它由 Codex、Claude Code 等 Agent 终端加载。SkillRun 不执行它，不把它暴露成 MCP tool，也不从 Markdown 推断 action。

Runtime Capsule = SOP 加 action、schema、examples、permissions 和 Manifest。它可以被 inspect、check、test、run、pack、import，并可按需通过 SkillRun Router 暴露为 MCP。

无 Manifest 合同，不执行。CLI 必须拥有两条交付路径的生命周期合同。Desktop 只展示和确认 CLI plan，不应自己发明安装路径、直接复制文件或绕过 rollback 语义。

项目定位

SkillRun 是面向 SOP-backed Agent 能力的 packaging、inspection and runtime layer。它不是 MCP-first：MCP 只是 Runtime Capsule 的一种调用面，不是产品身份。

Context Skill 让 Agent 学会一个流程。Runtime Capsule 把 SOP、schema、preflight、structured envelope、artifact 和 run evidence 绑定到可执行 action 上。MCP 只是在需要时把这些 capsule 暴露给兼容客户端。

SkillRun 不抢“把函数暴露成 tool”的战场。它解决的是另一个问题：当 Agent 调用真实工作时，SOP、输入输出结构、边界、失败恢复、产物和审计证据必须跟能力一起移动。

Runtime Capsule = SOP + action code + schema + examples + permissions + Manifest

信任模型 (Trust Model)

SkillRun 提供的是 manifest-bound execution and inspection layer，而不是 OS sandbox。它能减少 Agent 裸调 action 的风险，但运行别人分发的 action 仍然意味着执行别人写的代码。

SkillRun 中的护栏指 Manifest contract、input/output schema、preflight、structured envelope、artifact containment、run evidence 和 Consumer Mode static checks。

当前可信边界 (v0.6.8)：

  • Consumer Mode 不为 metadata extraction 动态 import 未信任源码。
  • Manifest 缺失、过期或 source hash 不匹配时 fail closed。
  • Runtime 只注入 Manifest 显式声明过的业务环境变量。
  • stdout/stderr 只作为过程日志；结构化结果必须来自 output/error envelope。
  • Artifact 路径被约束在 run-local 目录内。
  • .skr 是 source + Manifest archive，不是 secure install format。
  • switchboard enabled=true 是 exposure intent，不是 trust 或 sandbox 证明。
  • runs list 和本地 index 默认保持 summary-only；不会把 input、envelope body、stdout、stderr 复制进列表输出。
  • 结构化错误会为 Agent 提供可恢复行为建议。

    • 当前不承诺的能力：

  • 完整 OS sandbox 或文件系统隔离。
  • 强制网络出口隔离或恶意代码检测。
  • 自动安装 Python、Node、npm 或 pip 依赖。
  • Public marketplace trust、可复现运行时镜像或签名包信任体系。

    • Agent 引导提示词

    把这段提示词发给 AI，让它先区分 Context Skill 与 Runtime Capsule，再决定是否安装或调用。

    [SKILLRUN BOOTSTRAP]
我们使用 SkillRun (https://github.com/iiwish/skillrun) 管理带明确边界的 Agent 能力。

1. 先判断 artifact 类型：
   - Context Skill：SKILL.md 加 references/scripts/templates；只加载/阅读，不通过 SkillRun 执行。
   - Runtime Capsule：SKILL.md 加 action、schema、examples、permissions 和 Manifest；使用前必须 inspect/check/test。
2. 阅读 GitHub README 和相关文档后，再决定是否安装或调用。
3. 使用 Runtime Capsule 前，必须阅读其 `SKILL.md`；若有本地访问权限，运行 `skillrun inspect` 和 `skillrun check`。
4. 尊重所有 preflight 边界；业务结果只看 structured output/error envelope，stdout/stderr 只作为日志。
5. MCP 是 Runtime Capsule 的可选调用面，不是 SkillRun 的定义。
    Click to Select All