38 · Agent 技能（Agent Skills）

Agent Skills 提供了一种标准化方式，用可复用、可共享的技能包来扩展 Agent 能力。 技能是动态加载的，为 Agent 提供指令、资源与工具。

Embabel 实现了 Agent Skills 规范（Agent Skills Specification）。

什么是 Agent Skill？

一个 Agent Skill 就是一个目录，其中包含一个带 YAML frontmatter 与 markdown 指令的 SKILL.md 文件。 技能还可以包含打包的其它资源：

• scripts/ —— 可执行脚本（Python、Bash 等）
• references/ —— 文档与参考资料
• assets/ —— 模板、数据文件等静态资源

技能使用惰性加载（lazy loading）模式：system prompt 里只放最小元数据， 完整指令在技能被激活时才加载。

在 PromptRunner 中使用技能

Skills 类实现了 LlmReference，因此可以传给 PromptRunner：

var skills = new Skills("financial-skills", "Financial analysis skills")
        .withGitHubUrl("https://github.com/wshobson/agents/tree/main/plugins/business-analytics/skills");

var response = context.ai()
        .withLlm(llm)
        .withReference(skills)
        .withSystemPrompt("You are a helpful financial analyst.")
        .respond(conversation.getMessages());

把技能作为 reference 加入后，Agent 就能：

• 在 system prompt 中看到可用技能；
• 激活技能以获取完整指令；
• 列出并读取技能资源。

从 GitHub 加载技能

最简单的方式是从 GitHub URL 加载：

var skills = new Skills("my-skills", "Skills for my agent")
        .withGitHubUrl("https://github.com/anthropics/skills/tree/main/skills");

支持的 URL 格式：

• https://github.com/owner/repo —— 从仓库根目录加载；
• https://github.com/owner/repo/tree/branch —— 指定分支；
• https://github.com/owner/repo/tree/branch/path/to/skills —— 指定路径。

需要更多控制时，用显式参数：

var skills = new Skills("my-skills", "Skills for my agent")
        .withGitHubSkills("anthropics", "skills", "skills", "main");

从本地目录加载技能

从包含 SKILL.md 的目录加载单个技能：

var skills = new Skills("my-skills", "Local skills")
        .withLocalSkill("/path/to/my-skill");

从父目录加载多个技能：

var skills = new Skills("my-skills", "Local skills")
        .withLocalSkills("/path/to/skills-directory");

withLocalSkills 只扫描直接子目录（深度 1），不会递归进嵌套目录。

技能目录结构

技能目录必须包含 SKILL.md：

my-skill/
├── SKILL.md      # 必需 —— 元数据与指令
├── scripts/      # 可选 —— 可执行脚本
├── references/   # 可选 —— 文档
└── assets/       # 可选 —— 静态资源

SKILL.md 使用 YAML frontmatter：

---
name: my-skill
description: A skill that does something useful
license: Apache-2.0
compatibility: Requires Python 3.9+
---

# My Skill Instructions

Step-by-step instructions for using this skill...

技能激活（Skill Activation）

技能是惰性激活的。system prompt 中只包含最小元数据（每个技能约 50 ~ 100 token）。 当 Agent 需要某个技能时，它会调用 activate 工具来加载完整指令。

Skills 类暴露三个 LLM 工具：

• activate(name) —— 加载某技能的完整指令；
• listResources(skillName, resourceType) —— 列出 scripts/、references/、assets/ 中的文件；
• readResource(skillName, resourceType, fileName) —— 读取某个资源文件。

与其它 Reference 组合

技能可以与其它 LlmReference 实现组合使用：

var response = context.ai()
        .withLlm(properties.chatLlm())
        .withReference(
                new LocalDirectory("./data/financial", "Financial data files")
                        .withUsageNotes("Search to find files matching user requests.")
        )
        .withReference(
                new Skills("analytics", "Business analytics skills")
                        .withGitHubUrl("https://github.com/example/skills/tree/main/analytics")
        )
        .withSystemPrompt("You are a financial analyst assistant.")
        .respond(conversation.getMessages());

校验（Validation）

技能在加载时会进行校验：

• Frontmatter 校验 —— 必填字段（name、description）以及字段长度；
• 文件引用校验 —— 指令里提到的路径（例如 scripts/build.sh）必须存在；
• 名称匹配 —— 技能名必须与其父目录名一致。

要关闭文件引用校验：

var loader = new DefaultDirectorySkillDefinitionLoader(false);

当前限制（Current Limitations）

• 脚本执行：带 scripts/ 目录的技能可以被加载，但尚不支持执行脚本。加载这类技能时会输出一条警告日志。
• allowed-tools 字段：frontmatter 中的 allowed-tools 会被解析，但目前不会强制执行。

完整规范见 Agent Skills Specification。