Skill 技能

Skill（技能）是可复用的、带 Fronmatter 说明的 Markdown 文档，用于把某一类工作流沉淀成可加载的知识片段。CLI 通过 @ai-zen/agents-sdk 发现与加载 Skill，并提供两个动态工具：load_skill 与 call_skill_sub_agent。

Skill 目录结构

每个 Skill 是一个目录，内含 SKILL.md：

~/.ai-zen/skills/my-skill/SKILL.md

项目级 Skill 位于项目目录下：

/path/to/project/.ai-zen/skills/my-skill/SKILL.md
/path/to/project/.agents/skills/my-skill/SKILL.md

目录优先级

Skill 目录从多个来源由高到低合并（来自 src/agent-creator.ts 的 getScope() 与 src/config.ts 注释）：

1. 项目 ./.ai-zen/skills/
2. 项目 ./.agents/skills/
3. 用户级 ~/.ai-zen/skills/
4. 用户规范 ~/.agents/skills/

动态工具

• load_skill：把 Skill 文档加载到上下文中（幂等，重复调用会跳过重复注入）。枚举由 filteredSkills 提供完整信息，不限是否支持子 Agent。
• call_skill_sub_agent：将一个任务委托给 Skill 子 Agent。仅对 frontmatter 含 sub-agent: true 的 Skill 生效，枚举中自动排除不支持子 Agent 模式的 Skill。

Skill 子 Agent 与权限

由 call_skill_sub_agent 创建的临时 Skill 子 Agent，作为一次性的对话代理存在。它是权限体系中的唯一例外：

• 普通子 Agent（带 function 字段的 Agent）拥有独立权限，不与父 Agent 继承。
• Skill 子 Agent 作为临时代理，沿用调用者的工具能力（ctx.agent.tools），不再走第二遍权限过滤，并非独立实体；同时剔除 call_skill_sub_agent 自身，防止链式自递归。

该路径同样经过子 Agent 委派边界（onSubAgentStart / onSubAgentEnd 钩子与 sub-agent-start / sub-agent-end 事件），因此子 Agent 上下文护栏与流式渲染同样覆盖技能子 Agent。

相关配置

Skill 也可通过 .ai-zen / .agents 下的 skills/ 目录按项目共享。CLI 在 ensureConfigDir() 中通过 SDK 的 ConfigManager.bootstrap() 初始化共享目录。