本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

技能与插件目录

状态：生效范围：公开、当前状态最近审阅：2026-08-12 负责人：AX Code 运行时

可发现的内置技能登记，以及如何添加项目技能。

默认的 / 菜单是控制面（/plan、/review、/debug、/status、/model）。较旧的内置技能仍仅供智能体使用（skill 工具）。后端可靠性包也列为斜杠命令。

内置技能（随 `packages/ax-code/skills/` 发行）

技能	用途	斜杠
`debug-n-fix`	先调试再修复，并加以验证	使用 `/debug`
`debug-only`	不改代码的调查	仅智能体
`improve-overall`	广泛的质量改进	仅智能体
`improve-security`	以安全为重点的改进	仅智能体
`mcp`	MCP 设置指引	使用 `/mcp`
`run`	启动并观察应用	仅智能体
`simplify`	收紧最近更改的代码	仅智能体
`verify`	运行时验证报告	仅智能体
`verified-change`	仅在出现失败信号后编辑，然后重新运行同一检查	`/verified-change`
`safe-db-migration`	带有回滚说明地扩展、回填或收缩模式变更	`/safe-db-migration`
`api-contract`	以加性为先的公共 API 与模式演进	`/api-contract`
`incident-observability`	打补丁之前以证据为先的事故诊断	`/incident-observability`
`auth-boundaries`	认证与授权、租户隔离、否定测试	`/auth-boundaries`
`queue-worker`	幂等的队列与工作者变更，以及重复投递	`/queue-worker`
`ruby-on-rails`	不启动 Rails 进程的 Rails 惯例	仅智能体

技能使用带 YAML frontmatter 的 SKILL.md（name、description，可选 paths、allowed-tools）。

项目技能

把技能放在以下任一位置：

.ax-code/skill/<name>/SKILL.md 或 .ax-code/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md（Agents / Codex 兼容）
.claude/skills/<name>/SKILL.md（Claude Code 兼容）
.opencode/skills/<name>/SKILL.md

列出并校验：

ax-code            # TUI skill dialog
# or use the skill tool from a session

调用控制

AX Code 在发现技能时读取这些可选控制：

位置	字段	效果
`SKILL.md` 的 frontmatter	`disable-model-invocation: true`	保留显式的 `/skill-name` 命令，但把该技能排除在模型发现和直接的模型工具加载之外。
`SKILL.md` 的 frontmatter	`user-invocable: false`	从斜杠命令中省略该技能；除非另行禁用，模型调用仍然可用。
同级的 `agents/openai.yaml`	`policy.allow_implicit_invocation: false`	要求显式斜杠调用，包括通过 `.agents/skills` 导入的技能。

使用 YAML 布尔值 true 和 false。缺少控制则保留默认值。若多个来源不一致，限制性声明胜出。无效的控制类型或格式错误的附属策略会同时禁用两种调用模式，并在技能清单和运行时日志中产生调用诊断。使用技能之前请修正元数据。可选附属文件必须小于 64 KiB；那里不支持 YAML 文档分隔符和别名。

这些控制管理技能调用，独立于现有的智能体权限。用自然语言提及仅手动的技能，并不会授权模型加载它；请调用其斜杠命令。已声明的 allowed-tools 仍然是工作流说明，并不授予权限。

有界发现

模型最初收到的是技能摘要，而不是完整说明。系统提示和工具描述中的每个技能元数据块有 8,000 字符预算。在省略条目之前会先缩短描述；当列表仍超出该预算时，文件匹配的推荐优先。省略通知会说明如何获取更多摘要。这是字符限制，不是 token 计数，也不是性能保证。

skill 工具有两种互斥模式：

{"name":"api-contract"} 通过现有权限检查加载技能。
{"query":"database"} 搜索合格的名称和描述，而不加载技能正文。
{"query":"","offset":20} 使用上一次结果中的确切 nextOffset 继续列出。

搜索是字面的且不区分大小写。空查询列出合格技能。跟随 nextOffset 直到它不存在。仅手动和权限被拒绝的技能被排除在模型发现之外。过大的单个元数据条目会跳过并给出通知。名称和源优先级保持不变。

插件

在 ax-code.json 中配置插件：

{
  "plugin": ["file:///absolute/path/to/plugin.js"]
}

插件实现 @ax-code/plugin 钩子（tool.execute.before、tool.execute.after、shell.env、auth 等）。

回调生命周期

插件工厂在其输入中接收可选的 lifecycle。实例被释放或插件退役时，lifecycle.signal 会中止。用 lifecycle.onDispose(cleanup) 注册计时器、监视器和订阅。返回的函数会注销该清理。注册最多运行一次；在释放之后注册会立即开始清理。清理回调按注册的相反顺序开始，每个有一秒预算，并且可以并发完成。

转换钩子接收可选的第三个参数 { signal }；配置和事件钩子把它作为第二个参数接收。该信号在回调待处理时取消工作；对超出单次回调、由插件拥有的工作使用 lifecycle.signal。把信号传给可中止的操作。初始化、配置、事件和转换回调有 15 秒截止时间。超时会为该实例退役插件并中止其生命周期。现有工厂和双参数转换钩子继续可用。自定义工具执行和交互式认证保留其现有执行契约。

转换输入是对普通数据的只读观察。变更输出草稿，并在返回之前等待全部变更。成功的输出变更按注册顺序变得可见；失败或过晚的变更会被丢弃。事件载荷变更从不发布。权限拒绝仍然是拒绝，失败或已退役的权限钩子需要询问，除非已经存在拒绝。

数组和普通对象与运行时状态分离。模式、函数和类实例保留身份，必须当作只读。插件仍然是在运行时进程中运行的受信任 JavaScript：取消是协作的，不能停止同步无限循环，也不能撤销外部效果。

钩子包

五个官方生命周期包见钩子（format-after-edit、block-force-push、require-tests-on-stop、protect-env-files、log-bash-commands）。

评估框架

运行智能体运行时门控套件和多模式集成策略套件：

cd packages/ax-code
pnpm exec vitest run test/harness/agentic-runtime-eval.test.ts
pnpm exec vitest run test/harness/multi-mode-ensemble-eval.test.ts

本地、云端、混合、council 与 arena 另见执行模式。