> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> 了解 Agent Skills 标准，以及 SDK 的加载、注册和能力配置。

## 标准格式

Skill 采用 Anthropic 发起并发布为开放标准的 **Agent Skills** 格式，用来封装特定任务的指令、脚本和资源。其背景见 [Anthropic 的 Agent Skills 介绍](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)，格式定义以 [Agent Skills 官方规范](https://agentskills.io/specification)为准。

一个 Skill 是一个目录，入口为 `SKILL.md`：

* YAML frontmatter 必须包含 `name` 和 `description`，说明名称、用途和使用时机。
* Markdown 正文描述执行步骤、注意事项和示例。
* 可选的 `scripts/`、`references/`、`assets/` 存放脚本、参考资料和模板等资源。

标准采用渐进式加载：先识别元数据，激活时读取指令，需要时再读取附属资源。Skill 不只是 prompt 模板，也不等同于可调用的 Tool；执行其中的操作仍需要宿主提供相应工具和权限。

## 加载方式

SDK 不附带内建 Skill。可以通过 `registerSkill(definition)` 注册程序化定义，并用 `getAllSkills()` 读取所有已注册 Skill；也可以通过 `settingSources` 从文件系统加载：

| 选项                   | 说明                                                                           |
| -------------------- | ---------------------------------------------------------------------------- |
| `settingSources`     | 从 `~/.agents/skills/`（`user`）和/或 `${cwd}/.agents/skills/`（`project`）加载 Skill |
| `extraUserSkillDirs` | 额外的用户级 Skill 目录（标记为 `source='user'`）                                         |

程序化注册是 SDK 的扩展接口，不是 Agent Skills 标准要求的交付格式。标准的可选字段能否生效取决于宿主实现；不要把格式中的工具声明视为运行时权限授权。

## 配置可用性

Skill 属于 Agent-local 能力，应在配置 Agent 时显式指定：

* 根 Agent 使用 `agent.availableSkills`——仅根 Agent 生效、作用于运行时 Skill 注册表的 allowlist。
* Subagent 使用 `capabilities.skills`——Agent 自有 Skill 集合，绝不从父 Agent 继承，见 [Subagent](/zh/sdk/subagents)。

失效的通配符和零匹配 allowlist 都会记录警告。管理员或应用应明确授权需要的能力，便于审计和维护。