内容
# @zibby/skills
[](https://www.npmjs.com/package/@zibby/skills)
[](https://www.npmjs.com/package/@zibby/skills)
[](./LICENSE)
[Deutsch](./i18n/README.de.md) | [Español](./i18n/README.es.md) | [français](./i18n/README.fr.md) | [日本語](./i18n/README.ja.md) | [한국어](./i18n/README.ko.md) | [Português](./i18n/README.pt.md) | [Русский](./i18n/README.ru.md) | [中文](./i18n/README.zh.md)
📖 **完整文档：** [docs.zibby.app](https://docs.zibby.app) · [快速开始](https://docs.zibby.app/get-started/install) · [概念](https://docs.zibby.app/concepts/graph) · [CLI 参考](https://docs.zibby.app/cli-reference) · [云](https://docs.zibby.app/cloud/triggering)
> **[@zibby/agent-workflow](https://github.com/ZibbyDev/agent-workflow) 的技能层。** 内置技能定义，赋予工作流节点所需的工具 — 函数工具、MCP 服务器、浏览器、问题跟踪器、内存。供应商中立，以 JavaScript 为优先。
`@zibby/skills` 是 [`@zibby/agent-workflow`](https://github.com/ZibbyDev/agent-workflow) 的配套包（[npm](https://www.npmjs.com/package/@zibby/agent-workflow)）— *"基于图的 AI 代理工作流编排。"* 工作流引擎故意不包含任何技能；内置技能在此包中。
**技能** 是工作流节点与工具之间的契约。它告诉引擎工具的作用、如何启动它以及它需要什么。引擎永远不会硬编码任何技能名称 — 它读取技能定义并为 Claude 和 Cursor 代理通用连接。
```
@zibby/agent-workflow node @zibby/skills
────────────────────────── ─────────────
skills: ['add'] ──► getSkill('add')
│
▼
skill.resolve() → { command, args, env }
│
┌────────┴────────┐
▼ ▼
Claude SDK Cursor CLI
```
---
## 与 @zibby/agent-workflow 一起使用
您不能单独使用 `@zibby/skills` — 它与 [@zibby/agent-workflow](https://github.com/ZibbyDev/agent-workflow) 结合使用。节点在其 `skills:` 数组中命名所需的技能，工作流引擎在运行时解析它们：
```bash
npm install @zibby/agent-workflow @zibby/skills
```
```javascript
// 1. 导入包以注册所有内置技能
import '@zibby/skills';
```
定义一个技能一次…
```javascript
import { skill } from '@zibby/skills';
export const add = skill('add', {
description: '添加两个数字',
input: { a: 'number', b: 'number' },
handler: async ({ a, b }) => ({ result: a + b })
});
```
…and 一个 **@zibby/agent-workflow 节点** 请求它：
```javascript
// 由 @zibby/agent-workflow 节点使用
export const mathNode = {
name: 'do_math',
skills: ['add'],
prompt: (state) => `添加 ${state.a} 和 ${state.b}`,
};
```
当引擎运行 `do_math` 时，它会看到 `skills: ['add']`，查找技能，调用 `resolve()`，并将生成的工具交给运行节点的代理。有关节点、图和状态如何组合在一起，请参阅 [`@zibby/agent-workflow`](https://www.npmjs.com/package/@zibby/agent-workflow)。
---
## 快速开始
```bash
npm install @zibby/skills
```
导入包以注册所有内置技能：
```javascript
import '@zibby/skills';
```
---
## `skill()` 工厂
一个函数来创建任何技能。自动检测类型并自动注册。
### 函数技能
一个技能 = 一个工具。扁平的，没有嵌套。
```javascript
import { skill } from '@zibby/skills';
export const add = skill('add', {
description: '添加两个数字',
input: { a: 'number', b: 'number' },
handler: async ({ a, b }) => ({ result: a + b })
});
```
在 @zibby/agent-workflow 节点中使用：
```javascript
export const mathNode = {
name: 'do_math',
skills: ['add'],
prompt: (state) => `添加 ${state.a} 和 ${state.b}`,
};
```
### MCP 技能
用于包装现有的 MCP 服务器包：
```javascript
import { skill } from '@zibby/skills';
export const linear = skill('linear', {
envKeys: ['LINEAR_API_KEY'],
description: '线性问题跟踪器',
resolve() {
if (!process.env.LINEAR_API_KEY) return null;
return {
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-linear'],
env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY },
};
}
});
```
---
## 内置技能
| ID | 服务器 | MCP 包 |
|----|--------|-------------|
| `browser` | `playwright` | `@zibby/mcp-browser` / `@playwright/mcp` |
| `jira` | `jira` | `@zibby/mcp-jira` |
| `github` | `github` | `@modelcontextprotocol/server-github` |
| `slack` | `slack` | `@modelcontextprotocol/server-slack` |
---
## 函数技能 API
```javascript
skill(id, { description, input, handler })
```
- `id` — 唯一的技能标识符（用于 `skills: ['add']`）
- `description` — 工具的作用（显示给 LLM）
- `input` — 参数定义：
```javascript
{
param: { type: 'string' }, // 完整形式
other: 'number', // 简写
optional: { type: 'string', required: false },
}
```
- `handler` — 调用工具时运行的函数：
```javascript
handler: async ({ param, other }) => {
return { result: 'something' }; // 任何 JSON 可序列化值
}
```
### 处理器规则
- 必须是 `async`（或返回 Promise）
- 接收一个带有输入参数的对象参数
- 必须返回一个 JSON 可序列化值
- 可以访问导入、闭包和模块范围
- 在子进程中运行（函数桥）
### 更多示例
```javascript
import { skill } from '@zibby/skills';
export const fetchUrl = skill('fetch_url', {
description: '获取 URL 并返回响应体',
input: { url: 'string' },
handler: async ({ url }) => {
const res = await fetch(url);
return { status: res.status, body: await res.text() };
}
});
export const healthCheck = skill('health_check', {
description: '检查服务是否正在运行',
handler: async () => ({ status: 'ok', timestamp: Date.now() })
});
```
---
## MCP 技能 API
```javascript
skill(id, config)
```
配置对象：
| 属性 | 必需 | 描述 |
|---|---|---|
| `resolve(options)` | 是 | 返回 `{ command, args, env }` 或 `null` |
| `serverName` | 否 | MCP 服务器名称（默认为 `id`） |
| `allowedTools` | 否 | 工具模式（默认为 `['mcp__<serverName>__*']`） |
| `envKeys` | 否 | 技能需要的环境变量 |
| `description` | 否 | 人类可读的描述 |
| `tools` | 否 | 用于编译时验证的工具模式 |
| `cursorKey` | 否 | 重写 `~/.cursor/mcp.json` 中的键 |
| `sessionEnvKey` | 否 | 会话工件路径的环境变量（仅限 Cursor） |
### 高级示例：自定义二进制文件和备用方案
```javascript
import { skill } from '@zibby/skills';
import { createRequire } from 'module';
const _require = createRequire(import.meta.url);
export const database = skill('database', {
envKeys: ['DATABASE_URL'],
description: '数据库查询 MCP 服务器',
resolve({ sessionPath } = {}) {
let bin;
try { bin = _require.resolve('@myorg/mcp-database/server.js'); }
catch { bin = null; }
if (bin) {
return {
command: 'node',
args: [bin, '--read-only'],
env: { DATABASE_URL: process.env.DATABASE_URL },
};
}
return {
command: 'npx',
args: ['-y', '@myorg/mcp-database', '--read-only'],
env: { DATABASE_URL: process.env.DATABASE_URL },
};
}
});
```
---
## 底层工作原理
```
节点定义 技能定义 代理策略
───────────── ──────────────── ──────────────
skills: ['add'] ──► getSkill('add') ──► 策略特定设置
│
▼
skill.resolve()
│
▼
{ command, args, env }
│
┌────────┴────────┐
▼ ▼
Claude SDK Cursor CLI
────────── ──────────
内存 写到
mcpServers ~/.cursor/mcp.json
参数到 在启动前
query() `agent` CLI
```
**Claude**：SDK 接收 `mcpServers` 作为参数。它将 MCP 服务器作为子进程启动，通过 stdio 连接，并通过它路由工具调用。
**Cursor**：引擎在启动 `agent` CLI 之前将 `~/.cursor/mcp.json` 写入磁盘。Cursor 读取该文件并自行管理 MCP 服务器。
策略永远不会按名称引用任何技能。它们会遍历技能定义并在每个定义上调用 `resolve()`。
---
## API
```javascript
import {
skill, // 统一工厂 — 自动检测类型，自动注册
registerSkill, // 注册原始技能定义
getSkill, // 按 ID 获取技能
hasSkill, // 检查技能是否已注册
getAllSkills, // 获取所有已注册的技能（映射）
listSkillIds, // 获取已注册的技能 ID 数组
SKILLS, // 内置技能 ID 常量
} from '@zibby/skills';
```
---
## 配套包
| 包 | 添加内容 |
|---|---|
| [`@zibby/agent-workflow`](https://www.npmjs.com/package/@zibby/agent-workflow) | 图引擎。技能在此处插入节点。 |
| [`@zibby/cli`](https://www.npmjs.com/package/@zibby/cli) | `zibby` 命令 — 脚手架、开发服务器、部署、触发、日志。 |
| [`@zibby/core`](https://www.npmjs.com/package/@zibby/core) | 内置代理策略（Claude / Cursor / Codex / Gemini / OpenAI Assistant）、MCP 客户端、运行时。 |
---
## 许可证
MIT
