Skillscript 完全指南：用声明式语言为 AI Agent 编排可复用的技能工作流

概述

当你的 Claude Code 或 Codex Agent 每次执行重复任务时都要从头推理，不仅浪费 token，还容易产生行为漂移——同一个操作两次运行的结果可能截然不同。Skillscript 正是为解决这个问题而生的：它是一种声明式的、受 Makefile 启发的 DSL，让 AI Agent 将学会的流程”凝固”为可命名、可版本化、可审批的技能工件。

简单来说：Agent 用自然语言写一个 Skill，你审批后，它就能精确执行——不再重复规划、不再偏离步骤、不再让 Token 白白流失。

项目地址：https://github.com/sshwarts/skillscript

文档站：https://docs.skillscript.ai

许可：MIT | 语言：TypeScript | 当前状态：pre-1.0（核心已稳定）

架构：Skillscript 的四大组件

Skillscript 的架构围绕着编写 → 审批 → 执行 → 观测四个阶段展开：

1. skillfile CLI：终端命令行工具，负责初始化项目、审批技能、执行技能、查看状态
2. Runtime：后台运行的服务，管理技能的执行生命周期、安全策略和凭证
3. MCP Server：暴露标准 MCP 端点（http://localhost:7878/rpc），让任何 MCP 兼容的 Agent 都可以连接到 Runtime
4. Dashboard：Web 界面（http://localhost:7878），用于可视化管理技能和查看执行记录

Agent 通过 MCP 写入 Skill → 人类在 Dashboard 中审批 → Runtime 安全执行 → 跟踪日志持久化。这四个组件构成了一个完整的”Agent 自动化流程闭环”。

安装与环境配置

一行命令安装

npm install -g skillscript-runtime

安装后，用 skillfile init 初始化你的首个项目：

skillfile init
skillfile dashboard --host 127.0.0.1 --port 7878

打开 http://localhost:7878 即可看到 Dashboard。建议只在本地绑定 127.0.0.1；需要让其他容器或远程机器访问时，使用 --host 0.0.0.0 并做好网络防护。

连接 AI Agent

在 Claude Code、Cursor 或 Codex 的 MCP 配置中添加：

{
  "mcpServers": {
    "skillscript": {
      "type": "http",
      "url": "http://localhost:7878/rpc"
    }
  }
}

连接后，Agent 就能通过 MCP 自动发现 skillscript 的工具集——你只需用自然语言告诉 Agent 你想要什么样的自动化即可。

核心概念：什么是 Skill？

Skillscript 中的 Skill 是一个带类型的声明式工作流。看一个最简单的示例：

Hello, ${WHO}!

这个 Skill 使用变量 WHO（默认值 world），输出时将其渲染出来。它之所以称为”技能”（Skill），是因为它把 Agent 能做的事情封装成了一个可重复执行的单元——比直接让 Agent 重新推理更稳定、更高效。

三种 Skill 角色

更复杂的 Skill：带 Connector 和触发器的

Snapshot written for ${NOW}.

snapshot:
    shell(command="df -h --output=source,pcent,target") -> USAGE
    file_write(
        path="/var/log/skillscript/disk-${EVENT.fired_at_unix}.txt",
        content="${USAGE}"
    )

default: snapshot

这个 Skill 每天 6:00 自动执行，使用 shell 连接器获取磁盘使用情况并写入日志文件。Runtime 会依据你设定的白名单策略决定是否允许执行 shell 和 file_write 操作——默认情况下所有二进制和路径都是拒绝的，需要你在配置中显式放行。

安全模型：让 Agent 自动化不失控

这是 Skillscript 的设计亮点。对比直接让 Agent 跑 Python 脚本或 Bash：

关键的环境变量控制项：

功能详解：skillfile CLI 命令全览

skillfile 是操作 Skillscript 的核心 CLI，安装后立即可用：

执行 skillfile --help 可查看每个命令的详细参数。

工作流程：从创建到执行

第一步：Agent 编写 Skill

在 Claude Code 中连接好 MCP 后，你只需说：

“帮我创建一个 Skill，每天早上 8 点检查服务器磁盘使用情况，如果超过 80% 就通知我。”

Agent 通过 MCP 的 skillscript 工具写入 Skill 文件。在安全模式下，这个 Skill 会以 Draft 状态创建——它不会被执行，需要你的审批。

第二步：人类审批

在 Dashboard 或 CLI 中：

skillfile approve daily-disk-check

审批后 Skill 变为 Approved 状态。如果开启了 Secured Mode，审批会用操作员证书签名，确保变更可追溯。

第三步：执行与观测

手动执行：

skillfile execute daily-disk-check

或者等待 Cron 触发器自动触发。所有的执行记录、输出、失败信息和被阻止的操作都会被 Runtime 追踪记录，你可以用 skillfile replay 回放任何一次执行的完整过程。

连接器（Connectors）体系

Skill 的能力边界由 Connectors 定义。Connectors 可以暴露 MCP 工具、数据存储、本地模型、Agent 交付渠道或自定义能力。它们作为 Skill 与外界的唯一通道，确保每个对外操作都在受控范围内执行。

内置 Connector 包括：

• Shell Connector：通过白名单执行系统命令
• File Connector：通过白名单读写文件
• HTTP Connector：向外部 API 发送请求
• SQLite Connector（可选）：通过 sqliteSkillStore 存储技能数据

Runtime 持有的凭证（Secrets）会被定向传递给已审批的 Connector 目标，Skill 自身无法打印或检查其原始值——这一点从根本上杜绝了凭证泄露的风险。

排错与注意事项

1. Port 冲突：如果 7878 端口被占用，用 skillfile dashboard --port 7879 指定其他端口。

2. MCP 连接失败：确认 Runtime 已启动（skillfile health），且 Agent 的 MCP 配置中的 URL 与 Dashboard 绑定的地址一致。

3. Skill 无法执行：检查 Skill 的状态是否为 Approved。未审批的 Draft 状态不会执行。

4. Shell 命令被拒绝：查看 SKILLSCRIPT_SHELL_ALLOWLIST 配置——默认所有二进制文件都被拒绝。在环境变量或 config.toml 中放行你信任的命令。

5. 预发布状态：Skillscript 目前为 pre-1.0，核心语言和 Connector 契约正在稳定化。更新前请查阅 UPGRADING.md。

总结

Skillscript 回答了一个关键问题：当 AI Agent 编写自动化脚本的速度超过人类审查的速度时，如何确保安全性和可重复性？

答案是用一种受限的 DSL 取代通用脚本语言——Agent 编写在表达能力受限但安全可控的范围内，人类审查时看到的是完整的”效果表面”而非逐行代码。对于需要 Agent 执行重复工作流的团队来说，Skillscript 提供了一条从”每次重新推理”到”一次编写、反复执行”的演进路径。

相关链接：

• GitHub 仓库
• 官方文档
• 语言参考
• 安装命令：npm install -g skillscript-runtime