Agent Skills 是把可复用的任务知识、操作步骤和配套资源组织为目录，使 Agent 能在任务需要时按需加载并执行的一种能力封装形式。一个 Skill 不只是提示词片段：它可以包含说明文档、脚本、参考资料、模板和其他资产，并明确触发场景、环境要求与执行边界。
基本结构
开放的 Agent Skills 规范要求每个 Skill 目录至少包含一个 SKILL.md 文件。常见结构如下：
skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md 使用 YAML frontmatter 声明名称和描述，正文写入操作步骤、示例和边界。scripts/ 放置可执行程序，references/ 保存按需查阅的详细资料，assets/ 保存模板、示例文件等静态资源。具体实现可以支持额外字段和目录，因此使用前应检查运行环境的兼容规则。
触发与渐进式披露
Skills 通常采用分层加载：
- Agent 启动时只看到名称和描述，用于判断哪些 Skill 可能相关；
- 任务命中后读取完整
SKILL.md； - 只有执行到具体步骤时，才继续读取被引用的脚本、参考资料或资产。
这种渐进式披露避免把所有操作手册一次性放入上下文。描述既是目录摘要，也是触发条件，应同时说明 Skill 做什么、何时使用以及不适用的情况。
与工具的关系
模型原生工具通常通过结构化 Schema 约束参数，并由 Harness 直接调用实现；Skill 主要通过自然语言指导 Agent 使用已有工具、命令或脚本。两者可以组合：Skill 负责跨步骤流程和领域知识，专用工具负责复杂参数、权限、审计或高风险操作。
Skill 并不天然比工具更安全。若它调用 Shell 或代码解释器，实际权限由这些底层工具和执行环境决定。能力采用 Skill 还是专用工具，应按安全、参数复杂度、变更频率和模型能力选择，详见 Agent 工具设计。
与 MCP 和工具发现的关系
Model Context Protocol（MCP）是 AI 应用与外部能力之间的互操作协议；Skills 是描述和组织任务能力的开放目录形式。Skill 可以调用 MCP 工具，也可以经由 MCP、Skill Hub、代码仓库或本地目录分发，两者不是替代关系。
Skills 的元数据目录本身是一种轻量的能力发现机制，但工具规模很大时仍可能需要分组、检索和按需加载。更一般的规模化问题见 Agent 工具发现。
编写原则
- 让名称稳定，描述明确覆盖触发条件和边界；
- 主文件保持聚焦，把长参考资料拆到按需读取的文件；
- 步骤使用可验证的输入、输出和完成条件；
- 脚本应明确依赖、错误信息和重复执行行为；
- 文件引用使用稳定相对路径，避免过深的引用链；
- 区分只读、可逆写入和高风险操作，并保留必要的人工确认；
- 用真实任务验证触发准确率、执行成功率和上下文开销。
安全与供应链
第三方 Skill 的 Markdown 可能包含恶意指令，脚本还可能读取本地文件、访问网络或下载依赖。安装和执行前应检查来源、许可证、版本、文件内容、依赖和所需权限；不可信 Skill 应在隔离环境中运行，并避免接触凭据和敏感数据。安全扫描只能降低风险，不能替代权限隔离和人工判断。
Agent 还应把 Skill 内容视为低于系统规则和用户明确要求的工作说明，不能让其中的文字自行扩大权限范围。