Agent Skill规范、构建与设计模式

来源类型： 微信公众号文章
日期： 2026-06-02
标签： AI, OpenClaw, 电商, 办公效率, 网络安全, 编程, 区块链, 大模型
原文链接： https://mp.weixin.qq.com/s/LCpiLyLnRn5WyuHpribyHw

摘要

阿里妹导读文章从 Skill 的规范格式、三层渐进式加载机制、模型驱动触发逻辑出发，深入解析 Skill-Creator 的工程化开发范式。（文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。）前言 Skill 不是 Prompt——它是围绕任务、工具、流程和输出边界的结构化行为设计。写好 Skill 的关键在于理解规范标准、掌握构建方法论、选择合适的设计模式。一、Skill 规范标准 1.1 什么是 Agent Skill 在 AI Agent 生态中，Skill 是一种可复用的 Prompt 增强包，通过渐进式加载机制为 Agent 注入领域...

核心内容

阿里妹导读

文章从 Skill 的规范格式、三层渐进式加载机制、模型驱动触发逻辑出发，深入解析 Skill-Creator 的工程化开发范式。（文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。）

前言

Skill 不是 Prompt——它是围绕任务、工具、流程和输出边界的结构化行为设计。写好 Skill 的关键在于理解规范标准、掌握构建方法论、选择合适的设计模式。

一、Skill 规范标准

1.1 什么是 Agent Skill

在 AI Agent 生态中，Skill 是一种可复用的 Prompt 增强包，通过渐进式加载机制为 Agent 注入领域知识和工作流程。2025 年 12 月，Anthropic 将 Skill 规范作为开放标准发布，目前已被 33+ 个 Agent 产品采纳，包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等。

一个 Skill 的最小形态只需要一个文件：

-

skill-name/├── SKILL.md # 必需：YAML 元数据 + Markdown 指令├── scripts/ # 可选：可执行脚本├── references/ # 可选：按需加载的参考文档└── assets/ # 可选：模板、资源文件
1.2 SKILL 格式规范

根据Anthropic提出的规范，SKILL.md 由 YAML frontmatter（元数据）和 Markdown body（指令正文）两部分组成。

YAML frontmatter 字段：

字段

是否必填

说明

约束

name

是

Skill 的唯一标识名

最多 64 个字符，仅允许小写字母、数字和连字符，不能以连字符开头或结尾，不能包含连续连字符，必须与所在文件夹名一致

description

是

描述这个 Skill 做什么、什么时候使用

最多 1024 个字符，不能为空，应该包含帮助 AI 识别相关任务的关键词

license

否

许可证信息

许可证名称或指向许可证文件的引用

compatibility

否

环境兼容性要求

最多 500 字符，说明需要的运行环境或依赖

metadata

否

自定义扩展元数据

键值对映射，可存储规范之外的额外属性

allowed-tools

否

预授权工具列表

空格分隔的字符串，实验性功能

1.2.1 name 字段的命名规则

name 字段有严格的命名规则：

必须为 1-64 个字符
只能包含 Unicode 小写字母数字字符（a-z）和连字符（-）
不能以连字符 ( -)开头或结尾
不得包含连续的连字符（--）
必须与父目录名称匹配

合法示例：

-

name: pdf-processingname: data-analysisname: code-review
非法示例：

-

name: PDF-Processing # 不允许大写字母name: -pdf # 不能以连字符开头name: pdf--processing # 不允许连续连字符

1.2.2 description 字段的写法建议

description 应该清晰描述 Skill 的功能和适用场景：

必须为 1-1024 个字符
应该描述该技能的作用以及何时使用。
应包含有助于代理识别相关任务的特定关键词。

好的示例：

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
差的示例：
description: Helps with PDFs.

1.2.3 Markdown 正文内容

元数据之后的 Markdown 正文部分就是 Skill 的核心指令。对正文格式没有硬性限制，只要能帮助 AI 有效执行任务即可。

建议包含以下内容：分步骤的操作说明、输入输出示例、常见边界情况处理。

建议正文控制在 500 行以内。如果内容较多，可以把详细的参考资料拆分到单独的文件中。

1.2.4 最简示例

一个最简的 SKILL.md 只需要 name 和 description：

-

---name: skill-namedescription: A description of what this skill does and when to use it.---

1.2.5 包含可选字段的示例

-

---name: pdf-processingdescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.license: Apache-2.0metadata: author: example-org version: "1.0"---

PDF Processing

When to use this skillUse this skill when the user needs to work with PDF files...

How to extract text1. Use pdfplumber for text extraction...

1.2.6 文件引用规范

在 SKILL.md 中引用其他文件时，请使用相对于 Skill 根目录的路径。例如：

引用参考文档：references/REFERENCE.md
引用脚本：scripts/extract.py

建议文件引用保持在一层深度，避免深层嵌套的引用链。

1.2.7 可选目录结构

scripts/ 目录

存放 AI 可以运行的可执行代码。脚本应该是自包含的或明确说明依赖关系，包含有用的错误提示信息，并能妥善处理边界情况。常见支持的语言包括 Python、Bash 和 JavaScript。

references/ 目录

存放 AI 在需要时可以读取的补充文档，例如：REFERENCE.md（详细技术参考）、FORMS.md（表单模板或结构化数据格式）、或特定领域的文档（如 finance.md、legal.md）。

建议每个参考文件保持聚焦，因为 AI

...(内容截断，完整内容请查看原文)

本页由自动化脚本生成，待人工审核补充