SkillForge

English Documentation

SkillForge 是一个给 AI Coding Agent 使用的本地优先技能运行时。它把技能定义成可校验、可组合、可暴露为 MCP 的独立单元，让 Agent 能像“安装包”一样复用能力，同时通过白名单沙箱约束读写范围。

当前仓库处于 Phase 1 MVP 阶段，已经具备以下核心能力：

• Rust CLI：run、serve、validate

• skill.yml 严格校验，禁止未声明字段

• 基于白名单的本地文件读写沙箱

• macOS 上自动接入 Seatbelt 平台沙箱，可用性受宿主环境约束

• 面向技能执行的 Plan -> Act -> Observe -> Reflect 流程

• 更细粒度的工具执行轨迹与观察结果

• 技能评测与 CI 门禁：批量校验、批量评测、clippy、测试

• Token 预算截断，避免超预算模型调用

• Ollama 与 OpenAI-compatible 模型接入

• 通过 HTTP 暴露 MCP initialize / tools/list / tools/call 能力

• TypeScript Registry CLI，支持本地 search / publish / install，以及 GitHub Release 分发与同步

为什么是 SkillForge

很多 Agent 技能方案停留在“提示词片段”或“仓库模板”层面，缺少版本、依赖、权限与运行边界。SkillForge 试图补上这些基础设施：

• 技能有结构化清单：skill.yml

• 技能有执行边界：allow.read_paths / allow.write_paths / allow.net_hosts

• 技能有可复用入口：skillforge serve <skill>

• 技能有评测基线：eval.md

• 技能能被本地 Agent 和 MCP 客户端共同消费

Related MCP server: OpenSkill

当前能力边界

为了避免文档和实现脱节，这里明确当前版本的边界：

• 已实现的是 Phase 1 MVP，不是完整的技能包管理平台

• Registry 目前提供本地 SQLite + 包镜像目录实现的 CLI，并支持通过 GitHub Release 分发技能包和回同步远端元数据

• MCP 服务已支持技能枚举和 tools/call 调用，当前仍是单技能单端点模型

• 沙箱已支持逻辑白名单和 macOS Seatbelt 自动接入；若宿主环境拒绝 sandbox-exec，会自动回退到逻辑白名单模式

• 当前平台级沙箱主要覆盖文件工具调用，网络与更广义的进程能力仍待继续收紧

• 内置技能执行器仅覆盖 fix-ci、grep-ts、doc-gen 三个示例技能

仓库结构

.
├── core/        # Rust：CLI、技能加载、模型调用、沙箱、MCP
├── registry/    # TypeScript：SQLite 注册表原型
├── schemas/     # 预留：schema/协议相关资源
├── skills/      # 技能定义：skill.yml / SKILL.md / eval.md / references/
├── docs/        # 使用说明与技能编写文档
└── mirrors/     # 预留：镜像/同步相关目录

依赖要求

• Rust 工具链（项目当前在 rustc 1.85 环境下验证）

• Node.js 22+

• pnpm 9+

• sqlite3 命令行工具（Registry 测试需要）

• 可选：ollama，用于本地模型调用

快速开始

1. 安装依赖

pnpm install

2. 构建 Core CLI

cargo build -p skillforge-core

如果你想直接生成发布构建：

cargo build --release -p skillforge-core

3. 运行测试

cargo test
pnpm --filter registry test

4. 校验一个技能

cargo run -p skillforge-core -- validate fix-ci

这会加载 skills/fix-ci/skill.yml、SKILL.md、eval.md，并输出解析后的 manifest JSON。

5. 运行一个技能

使用 mock 响应可以在没有模型服务时快速验证流程：

SKILLFORGE_MODEL_MOCK_RESPONSE="计划已生成" \
cargo run -p skillforge-core -- run grep-ts --task "search publish" --token-budget 400

如果你已经启动了 Ollama，也可以直接走真实模型：

export OLLAMA_BASE_URL=http://127.0.0.1:11434
cargo run -p skillforge-core -- run fix-ci --task "修复当前仓库的 CI 配置"

6. 以 MCP 形式暴露技能

cargo run -p skillforge-core -- serve fix-ci --port 18080

启动后会在 http://127.0.0.1:18080/mcp 提供 MCP HTTP 入口。

CLI 命令

skillforge --help
skillforge run --help

当前命令如下：

• skillforge run <skill> --task <task> [--model <name>] [--token-budget <n>]

• skillforge serve <skill> [--port 18080]

• skillforge validate <skill>

• skillforge validate-all

• skillforge eval <skill>

• skillforge eval-all

全局参数：

• --repo-root <path>：指定仓库根目录，默认当前目录

模型配置

skill.yml 中的 model.provider 决定调用后端：

• ollama

• openai

• openai-compatible

相关环境变量：

• SKILLFORGE_MODEL_MOCK_RESPONSE：启用 mock 返回，适合本地联调

• OLLAMA_BASE_URL：默认 http://127.0.0.1:11434

• OPENAI_API_BASE：默认 https://api.openai.com/v1

• OPENAI_API_KEY：使用 OpenAI-compatible 接口时必需

Skill Manifest 概览

每个技能目录至少包含：

• skill.yml

• SKILL.md

• eval.md

示例：

name: grep-ts
version: 0.1.0
description: 在 TypeScript 代码中执行受限搜索并输出结果摘要。
adapter:
  kind: raw
origin:
  source: local
  ref_name: main
  sha: workspace
model:
  provider: ollama
  name: qwen3:8b
  max_input_tokens: 800
deps: []
tools:
  - read_file
  - list_dir
mcp:
  exposed: true
  description: 暴露 TypeScript 搜索技能给 MCP 客户端。
allow:
  read_paths:
    - registry
    - skills
  write_paths: []
  net_hosts: []
eval:
  fixtures:
    - registry/src

skill.yml 开启了 deny_unknown_fields，也就是未声明字段会直接校验失败。

示例技能

• fix-ci：读取并修复 .github/workflows/ci.yml

• grep-ts：在受限目录中搜索 TypeScript 代码

• doc-gen：更新仓库文档摘要

这些技能既是示例，也是当前运行时能力的集成测试样本。

Registry CLI

registry/ 当前提供一个 TypeScript 实现的本地注册表 CLI：

• search：按技能名或描述搜索本地注册表

• publish：把 skills/<name>/ 或指定技能目录发布到本地注册表；可选同步上传到 GitHub Release

• install：从本地注册表安装技能到目标目录；如果本地没有包快照，会回落到远端资产下载

• sync-github：从 GitHub Release 拉取技能元数据并写回本地 registry

• RegistryStore：基于 sqlite3 命令行维护本地 SQLite 库

默认数据目录位于 .skillforge/registry/，其中：

• registry.sqlite 保存索引元数据

• packages/<skill>/<version>/ 保存已发布的本地技能包快照

• archives/<skill>/<skill>-<version>.tar.gz 保存可分发的技能包归档

常用命令：

pnpm --filter registry cli -- publish fix-ci --repo-root .
pnpm --filter registry cli -- publish fix-ci --repo-root . --github-repo owner/repo
pnpm --filter registry cli -- search fix
pnpm --filter registry cli -- sync-github owner/repo
pnpm --filter registry cli -- install fix-ci --target-dir ./downloaded-skills

当前 GitHub Release 约定：

• 每个技能包资产命名为 <skill>-<version>.tar.gz

• 默认使用 v<version> 作为 release tag

• publish --github-repo 依赖本机安装 gh

• sync-github 使用 GitHub Releases API 拉取公开 release 元数据

开发约束

项目内约束以 AGENTS.md 为准，关键点包括：

• core/ 只放 Rust 运行时与校验逻辑

• registry/ 只放 TS 注册表逻辑

• skills/<name>/ 目录必须包含技能清单与说明

• 模型调用必须经过 token 预算控制

• 变更 skill schema 时，需要同步 Rust 校验器与示例技能

文档导航

• 快速上手

• 本地使用与命令别名

• 团队本地开发脚本方案

• 技能编写指南

• 远端 Registry 服务架构设计

• English README

• English Getting Started

• English Local Usage

• English Team Local Development

• English Skill Authoring Guide

Roadmap

接下来的自然方向包括：

• 多源远端 registry 聚合与认证