Tokeny Skills 扩展指南：超越标准的能力增强

综合讨论

用户76062026-05-1713700

Tokeny 在 Agent Skills 开放标准（agentskills.io）基础上，扩展了一系列实用字段，让技能作者能更精细地控制执行行为、资源管理和安全边界。本文介绍这些扩展字段的用法和最佳实践。

背景：Agent Skills 标准

Agent Skills 是由 Anthropic 发起的开放标准，定义了一种轻量级的技能打包格式——一个包含 SKILL.md 文件的目录。标准规定的 frontmatter 字段包括：

字段	必填	用途
`name`	是	技能标识符（kebab-case，≤64 字符）
`description`	是	描述技能功能和触发条件
`license`	否	许可证
`compatibility`	否	环境要求说明
`metadata`	否	任意键值对
`allowed-tools`	否	预批准工具列表（实验性）

这些字段足以描述"技能是什么"，但对于"技能如何执行"缺乏控制力。Tokeny 的扩展正是为了填补这一空白。

Tokeny 扩展字段一览

---
name: my-skill
description: 技能描述...

# ── Tokeny 扩展字段 ──
copy-resources:
  - scripts/
  - templates/config.json
write-guards:
  - pattern: "src/.*\\.tsx?$"
    condition: require_subtask
    message: "源码文件必须通过子任务委派写入"
allowed-tools:
  - Read
  - Write
  - Bash(npm:*)
disable-model-invocation: false
user-invocable: true
argument-hint: "<topic>"
tags:
  - frontend
  - react
context: fork
model: deepseek-r1
---

下面逐一介绍每个扩展字段。

1. `copy-resources` — 声明式资源部署

解决什么问题

技能包中常常附带脚本、模板、配置文件等资源。标准做法是通过 ${SKILL_DIR} 变量让 Agent 读取这些文件，但这有几个局限：

Agent 需要消耗工具调用和 token 来逐一读取文件
某些场景下用户需要在工作空间中直接使用这些文件（如运行脚本、引用模板）
大文件受 read_file 行数限制，需要分段读取

用法

copy-resources:
  - scripts/           # 复制整个目录
  - templates/base.html
  - assets/config.json

行为

时机：技能执行前自动完成（非加载时）
策略：基于 mtime 增量更新——只有源文件更新时才覆盖
安全：拒绝 .. 路径遍历和绝对路径，跳过符号链接

示例：数据分析技能

---
name: data-analysis
description: 对工作空间中的数据文件进行统计分析和可视化
copy-resources:
  - scripts/analyze.py
  - scripts/visualize.py
  - templates/report.html
---

# 数据分析

使用 `scripts/` 目录下的 Python 脚本进行分析：
1. 运行 `python scripts/analyze.py <数据文件>` 生成统计摘要
2. 运行 `python scripts/visualize.py <数据文件>` 生成图表
3. 将结果填入 `templates/report.html` 生成报告

执行时，这三个文件会自动出现在用户的工作空间中，Agent 可以直接通过 bash 运行它们。

对比：不使用 copy-resources

如果不声明此字段，Agent 只能通过 ${SKILL_DIR} 引用技能安装目录中的文件（只读访问）。适合技能只需要"读取参考资料"而不需要"在工作空间中部署文件"的场景。

2. `write-guards` — 声明式写入守卫

解决什么问题

某些技能涉及复杂的多步骤工作流——比如先研究、再规划、最后才写代码。如果 Agent 跳过前置步骤直接写文件，可能产出质量低下的结果。write-guards 让技能作者强制 Agent 遵循预定流程。

用法

write-guards:
  - pattern: "src/.*\\.tsx?$"
    condition: require_subtask
    message: "请先通过子任务完成研究和规划，再修改源码文件"
  - pattern: ".*\\.sql$"
    condition: require_subtask
    message: "SQL 文件修改必须先通过子任务验证方案"

字段说明

属性	类型	说明
`pattern`	正则表达式	匹配文件路径（大小写不敏感）
`condition`	枚举	目前仅支持 `require_subtask`
`message`	字符串	拦截时返回给 Agent 的错误提示

行为

当 Agent 尝试写入匹配 pattern 的文件时：

如果尚未启动子任务 → 返回 message，写入被拒绝
如果子任务已启动但未完成 → 提示等待子任务完成
如果子任务已完成 → 放行写入

这确保了 Agent 必须先通过 delegate_task 完成前置工作（如研究、方案设计），才能修改受保护的文件。

示例：前端组件开发技能

---
name: frontend-design
description: 设计并实现 React 前端组件，遵循研究-设计-实现流程
write-guards:
  - pattern: "src/components/.*\\.tsx$"
    condition: require_subtask
    message: "组件实现前必须先完成设计方案（通过子任务研究现有组件模式和设计系统）"
---

# 前端组件开发流程

## 第一步：研究（子任务）
委派子任务研究：
- 现有组件库的设计模式
- 相关组件的 API 设计
- 设计系统的约束

## 第二步：实现
基于研究结果编写组件代码...

3. `allowed-tools` — 工具权限预批准

标准 vs Tokeny 增强

标准定义 allowed-tools 为空格分隔的字符串。Tokeny 在此基础上增强了：

支持 YAML 数组格式（更清晰）
支持作用域模式语法：Bash(pattern:*)
跨生态兼容（自动映射 Claude Code / OpenClaw / Tokeny 工具名）

用法

allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(git:*)       # 仅允许 git 相关命令免审批
  - Bash(npm:*)       # 仅允许 npm 相关命令免审批

行为

声明在 allowed-tools 中的工具在技能执行期间跳过 HITL（人工审批），直接执行。这大幅提升了技能的自动化程度。

安全硬限制（无论如何声明都不会跳过审批）：

delete_file — 删除文件始终需要确认
无限制的 Bash（未指定模式）— 不会绕过审批

工具名映射

Tokeny 自动识别不同生态的工具命名：

Tokeny	Claude Code	OpenClaw
`read_file`	`Read`	`read_file`
`modify_file`	`Write` / `Edit`	`write_file`
`bash`	`Bash`	`execute_command`
`grep`	`Grep`	`grep`
`glob`	`Glob`	`glob`
`list_files`	`LS`	`list_files`

你可以使用任何一种命名，Tokeny 会自动解析。

4. `disable-model-invocation` — 禁止自动路由

用法

disable-model-invocation: true

行为

设为 true 时，该技能不会出现在 Agent 的自动路由列表中。LLM 无法通过 activate_skill 自动激活它，只能由用户手动通过 /技能名 触发。

适用场景

技能有副作用（如发送邮件、部署代码），不希望被意外触发
技能需要特定参数，自动路由可能传入不当参数
实验性技能，尚未准备好自动使用

5. `user-invocable` — 控制菜单可见性

用法

user-invocable: false  # 默认 true

行为

设为 false 时，该技能不会出现在 /指令 自动补全菜单中。用户无法通过 UI 手动触发它。

适用场景

纯内部技能，仅供其他技能或系统调用
底层工具技能，不适合直接面向用户

与 `disable-model-invocation` 的组合

`disable-model-invocation`	`user-invocable`	效果
`false`	`true`	完全可用（自动 + 手动）
`true`	`true`	仅手动 `/指令` 触发
`false`	`false`	仅自动路由触发
`true`	`false`	完全隐藏（仅系统内部调用）

6. `argument-hint` — 参数提示

用法

argument-hint: "<topic> [--depth=deep|shallow]"

行为

在用户输入 /技能名 时，自动补全菜单中显示此提示文本，帮助用户了解需要提供什么参数。

示例

---
name: web-research
description: 对指定主题进行深度网络研究
argument-hint: "<研究主题>"
---

用户在输入框看到：/web-research <研究主题>

7. `tags` — 语义标签

用法

tags:
  - frontend
  - react
  - component

也支持逗号分隔格式：

tags: frontend, react, component

当前用途

标签目前作为语义元数据存储，用于：

技能市场的分类和搜索
前端 UI 的标签展示和筛选
未来可能用于增强自动路由的匹配精度

8. `context` — 执行模式（规划中）

用法

context: fork  # 或 inline（默认）

设计意图

模式	说明
`inline`	技能指令注入当前 Agent 的系统提示词，共享对话上下文
`fork`	创建隔离的子 Agent 执行，独立上下文，不污染主对话

fork 模式适合：

长时间运行的研究任务
需要大量工具调用的复杂流程
不希望技能执行过程干扰主对话的场景

注意：fork 模式目前处于规划阶段，当前所有技能均以 inline 模式执行。

9. `model` — 模型指定（规划中）

用法

model: deepseek-r1

设计意图

允许技能作者指定执行该技能时使用的 LLM 模型。适用于：

需要特定模型能力的技能（如需要强推理能力的代码审查）
成本优化（简单技能使用轻量模型）

注意：此字段目前处于规划阶段，技能执行时使用用户当前选择的模型。

完整示例：公众号文章工作室

下面是一个综合运用多个扩展字段的实际技能：

---
name: mp-article-studio
description: >
  微信公众号文章创作工作室。从选题策划到排版输出的全流程辅助，
  支持多种文章类型（深度分析、教程、观点评论）。
  当用户需要撰写公众号文章时使用。
tags:
  - writing
  - wechat
  - content
copy-resources:
  - templates/
  - scripts/format.py
  - assets/styles.css
write-guards:
  - pattern: "output/.*\\.html$"
    condition: require_subtask
    message: "最终排版文件必须在完成大纲审核（子任务）后才能生成"
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(python:*)
argument-hint: "<文章主题> [--type=深度|教程|评论]"
---

# 公众号文章创作流程

## 资源说明
- `templates/` — 各类型文章的 Markdown 模板
- `scripts/format.py` — Markdown 转微信富文本排版工具
- `assets/styles.css` — 排版样式表

## 工作流程

### 1. 选题分析
分析用户提供的主题，确定文章类型和目标读者...

### 2. 大纲规划（子任务）
委派子任务完成：
- 竞品文章调研
- 关键论点梳理
- 结构大纲设计

### 3. 正文撰写
基于大纲逐段撰写...

### 4. 排版输出
运行 `python scripts/format.py output/article.md` 生成最终排版

变量替换

在技能指令（Markdown body）中，可以使用以下变量：

变量	说明
`$ARGUMENTS` / `$1`~`$9`	用户传入的参数
`${SKILL_DIR}`	技能安装目录的绝对路径
`${WORKSPACE}`	当前工作空间的绝对路径
`${CWD}`	当前工作目录（等同于 `${WORKSPACE}`）

示例

参考 `${SKILL_DIR}/references/style-guide.md` 中的写作规范。
将输出文件保存到 `${WORKSPACE}/output/` 目录。
用户的需求是：$ARGUMENTS

最佳实践

何时使用 `copy-resources`

场景	推荐方式
技能需要运行脚本	`copy-resources` — 脚本需要在工作空间中执行
技能需要参考文档	`${SKILL_DIR}` — 只读引用即可
技能需要输出模板	`copy-resources` — 用户可能需要自定义模板
技能需要大型数据文件	`${SKILL_DIR}` — 避免复制大文件到工作空间

何时使用 `write-guards`

技能有明确的"先研究后实现"流程
需要防止 Agent 跳过关键步骤
输出文件质量依赖前置分析的完成度

`allowed-tools` 的安全建议

尽量使用作用域模式（如 Bash(git:*) 而非 Bash）
只声明技能实际需要的工具
不要试图绕过 delete_file 的审批保护

总结

扩展字段	类别	状态	核心价值
`copy-resources`	资源管理	可用	零 token 消耗的资源部署
`write-guards`	安全控制	可用	强制工作流程顺序
`allowed-tools`	权限管理	可用	提升自动化程度
`disable-model-invocation`	路由控制	可用	防止意外触发
`user-invocable`	UI 控制	可用	控制菜单可见性
`argument-hint`	UX 增强	可用	引导用户输入
`tags`	元数据	可用	分类与搜索
`context`	执行模式	规划中	隔离执行上下文
`model`	模型控制	规划中	指定执行模型

这些扩展让 Tokeny 的技能系统在保持与 Agent Skills 标准兼容的同时，提供了更强大的控制能力。技能作者可以根据实际需求选择性使用这些字段，从简单的参数提示到复杂的工作流守卫，逐步增强技能的可靠性和用户体验。

评论与讨论

0/2000

还没有评论，分享你的体验吧。

Tokeny Skills 扩展指南：超越标准的能力增强

背景：Agent Skills 标准

Tokeny 扩展字段一览

1. copy-resources — 声明式资源部署

解决什么问题

用法

行为

示例：数据分析技能

对比：不使用 copy-resources

2. write-guards — 声明式写入守卫

解决什么问题

用法

字段说明

行为

示例：前端组件开发技能

3. allowed-tools — 工具权限预批准

标准 vs Tokeny 增强

用法

行为

工具名映射

4. disable-model-invocation — 禁止自动路由

用法

行为

适用场景

5. user-invocable — 控制菜单可见性

用法

行为

适用场景

与 disable-model-invocation 的组合

6. argument-hint — 参数提示

用法

行为

示例

7. tags — 语义标签

用法

当前用途

8. context — 执行模式（规划中）

用法

设计意图

9. model — 模型指定（规划中）

用法

设计意图

完整示例：公众号文章工作室

变量替换

示例

最佳实践

何时使用 copy-resources

何时使用 write-guards

allowed-tools 的安全建议

总结

评论与讨论

1. `copy-resources` — 声明式资源部署

2. `write-guards` — 声明式写入守卫

3. `allowed-tools` — 工具权限预批准

4. `disable-model-invocation` — 禁止自动路由

5. `user-invocable` — 控制菜单可见性

与 `disable-model-invocation` 的组合

6. `argument-hint` — 参数提示

7. `tags` — 语义标签

8. `context` — 执行模式（规划中）

9. `model` — 模型指定（规划中）

何时使用 `copy-resources`

何时使用 `write-guards`

`allowed-tools` 的安全建议