Skillscript 完全指南：让 AI 编码 Agent 用声明式语言编写持久化技能

每次让 AI 编码 Agent 做同一件事（总结日报、检查磁盘、格式化输出），它都要从头推理一遍——燃烧昂贵的 tokens，产生略微不同的结果，而且从不记住怎么做。Skillscript 换了个思路：让 Agent 自己编写声明式技能（Skill），一次编写、持久化运行、审计透明。

核心问题：Agent 没有「固化能力」的载体

现在的 AI Agent 依赖推理时态（inference-time transient）的工作方式：每个任务从零开始推理，没有持久化的可执行能力记录。这带来三个浪费：

• 成本：每次例行操作都用最贵的推理层
• 延迟：每次付全套推理成本
• 漂移：同一任务每次产生细微不同的结果

现有的大多数 Agent 基础设施项目关注 记忆（Memory）——会话召回、RAG 增强上下文。它们回答的是”Agent 知道什么”，但没有回答”Agent 会做什么”的持久化、可执行、可审计问题。Skillscript 专为回答后者而设计。

Skillscript 是什么

Skillscript 是一个声明式 DSL（领域特定语言），由 Agent 编写、由运行时执行。它的核心理念是编排（orchestration）而非计算——工具执行数据操作，技能只负责组合调用链。

Hello, ${WHO}!
Welcome to Skillscript.

这是一个完整的、可运行的 Skill——正文就是输出。同样的结构可以扩展到多阶段 DAG，支持分类输入、调用 LLM、查询数据存储、条件分支和子 Agent 编排。

安装与配置

第一步：安装运行时

npm install -g skillscript-runtime
skillfile init             # 初始化 ~/.skillscript/ — 配置、签名密钥、演示技能
skillfile dashboard        # 启动 Web 面板 + MCP 服务器

init 命令会创建 ~/.skillscript/ 目录结构，包括配置、签名密钥和示例技能。dashboard 在前台启动一个服务器（默认 http://localhost:7878），同时提供 Web 面板和 MCP 端点。

第二步：配置环境（可选）

运行时带有合理的默认值，你可以按需调整：

cp ~/.skillscript/.env.example ~/.skillscript/.env

关键配置项：

• SKILLSCRIPT_PORT — MCP 服务器端口（默认 7878）
• SKILLSCRIPT_SECURED_MODE — 开启后只运行经过密钥签名的 Skill
• SKILLSCRIPT_SHELL_ALLOWLIST — shell 命令白名单（默认全部拒绝）
• SKILLSCRIPT_FS_ALLOWLIST — 文件系统白名单（默认全部拒绝）

第三步：接入 AI Agent

对 Claude Code，直接请求：“Add the skillscript MCP server at http://localhost:7878/rpc“——Agent 会自动配置。

手动配置也很简单：

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

第四步：编写第一个技能

连接到 Agent 后，告诉它：“Author a skill that greets someone by name.”

Agent 通过 MCP 工具链自动完成：skill_list 发现可用能力 → skill_preflight 检查契约 → skill_write 编写技能（状态为 Draft）→ 你在面板上批准 → execute_skill 运行。

完整示例：自动磁盘检查技能

这是一个更真实的例子——定时执行的 Skill，无需手动触发：

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

关键点：

1. # Triggers: cron:"0 6 *" — 运行时自动注册定时调度
2. # Autonomous: true — 允许写操作自动执行
3. ${EVENT.fired_at_unix} + ${NOW} — 运行时自动填充的上下文变量
4. 默认拒绝安全模型— shell 和 file_* 操作需要显式白名单

运行前设置白名单：

export SKILLSCRIPT_SHELL_ALLOWLIST=df
export SKILLSCRIPT_FS_ALLOWLIST=/var/log/skillscript
skillfile execute daily-disk-check

CLI 命令速查

完整的创作者 + 运维生命周期覆盖：

连接器模型：五层解耦

Skill 不直接知道与什么交互。五个接口将语言与底层解耦：

MCP 工具面

运行时通过 MCP（/rpc 端点）暴露完整的工具表面，适用于外部 Agent 编写和观测：

这意味着任何支持 MCP 协议的 Agent（Claude Code、GPT、Cursor）都可以通过网络发现、编写、验证和运行 Skills。

三种技能类型

Skillscript 定义了三种层次的技能，覆盖从静态输出到动态自治的完整谱系：

1. 静态技能（Static Skills） — 固定模板输出，最简形式。上面的 hello 示例就是纯输出脚本，适合通知模板、报告头、格式化消息。

2. 编排技能（Orchestration Skills） — 多阶段 DAG，通过 needs: 依赖和 shell/file_* 原语编排操作管道。上面的 daily-disk-check 就是一个编排技能——先执行 shell 命令，再写文件输出。

3. 动态技能（Dynamic Skills） — 内置 AI 调用。当技能需要理解自然语言输入或做分类决策时，可以通过 $ llm 连接器（需配置 LocalModel）在技能内部调用本地模型，实现”技能内推理”。组合方式包括：

• inline(skill=...) — 将子技能内联到当前技能
• execute_skill(...) — 运行时调用另一个技能，支持返回值传递
• 条件分支 — 根据前一步的输出决定下一步走向

安全模型：默认拒绝

与大多数 Agent 工具不同，Skillscript 采用默认拒绝（Default-Deny）的安全模型：

• Shell 命令：所有二进制默认不可用，需要 SKILLSCRIPT_SHELL_ALLOWLIST 显式白名单
• 文件系统：所有路径默认不可写，需要 SKILLSCRIPT_FS_ALLOWLIST 显式白名单
• 签名模式：SKILLSCRIPT_SECURED_MODE=true 时，只执行经过操作员密钥签名的 Skill
• 审计追踪：每次执行生成 .provenance.json 旁侧文件，skillfile replay 可重放任意一次执行

这意味着 Agent 编写的技能无法逃脱你设定的边界——如果它试图删除 /etc 下面的文件，运行时直接拒绝，不等到操作系统报错。

适用场景

• 例行自动化：每日报告、磁盘检查、日志摘要 —— 一次编写每天运行
• 工具编排：组合多个 API/工具完成复杂工作流
• 审计敏感操作：所有操作有追踪记录，支持回放
• 团队协作：Skill 有 Draft/Approved 生命周期，可以审查后再启用
• Agent 技能市场：不同 Agent 共享同一套 SkillStore，技能可以跨 Agent 复用

总结

Skillscript 不是又一个 Agent 框架——它是一个让 Agent 自己编写持久化技能的声明式语言。14⭐/MIT 的规模还在早期，但 32K 字符的 README 和完整的 MCP 工具面说明项目的思路很清晰。如果你被 AI Agent 的”每次都要重来”困扰，值得一试。

• GitHub: github.com/sshwarts/skillscript
• 文档: skillscript.mintlify.app/docs
• npm: npm install -g skillscript-runtime