SkillYi经成为让智Neng体完成特定任务的核心入口。一个写得清晰、结构统一的 Skill 不仅Neng提升模型的执行效率，还Neng让团队在迭代时少走弯路。下面这篇文章将从「为什么要标准化」说起，逐层拆解「怎么Zuo」——从目录布局到元信息约定，再到实际工作流的组织方式，力求让每位读者在阅读完后douNeng拿起键盘，搭建出自己的第一套可复用 Skill。

想象一下：公司里有十支研发小组，各自为自己的项目写了上百条 Skill。Ru果没有统一的格式，后期维护会像拼图一样困难；新同事上手时只Neng靠「kan代码」而不是「查文档」。通过制定一套明确的规范，Ke以实现：

一致性：所有 Skill dou遵循相同目录结构和字段约束。

可搜索性：搜索引擎Neng够快速索引关键字段，提高内部检索效率。

跨平台兼容：无论是 Anthropic、OpenAI 还是本地 LLM，只要遵守约定，douNeng直接加载。

一个完整的 Skill 通常围绕一个根目录展开，Zui核心的是位于根目录下的 SKILL.md 文件，它相当于「导航中心」。下面给出一种被广泛采纳的组织方式，具体文件内容可根据业务深度自行裁剪。

my-skill/
├── SKILL.md            # 必备入口
├── scripts/           # 可选脚本集合
│   ├── run.py
│   └── helper.sh
├── references/        # 行业或项目领域知识库
│   ├── guidelines.md
│   └── examples.md
└── assets/            # 静态资源
    ├── templates/
    └── schemas/

为了让智Neng体在调用时不至于「盲目探索」，建议在该文件中依次出现以下五大块：

Name & Description：简洁明了地说明技Neng名称与适用场景。

Compatibility：列出支持的模型版本或运行环境。

Quick Start：提供 1~2 条Zui常用指令，让使用者立刻上手。

Domain Index：指向 references 中各子领域文档，并配以简短描述。

Standard Workflow：分步阐述完整执行流程，标记关键决策点。

Name 必须符合以下规则：

全小写，仅含字母、数字和连字符；

首尾不Neng是连字符；

No 连续两个连字符出现；

推荐使用动名词形式，如 alert-users, summarize-docs.

Description 则应包含两段文字：第一句概括功Neng，第二句点出适用行业或业务场景。这样既利于搜索，也方便非技术人员快速判断是否需要调用该 Skill。

The following flow shows a typical lifecycle that every skill should respect.

User Intent 捕获：AIAgent 读取用户意图关键词，然后匹配对应 Skill 名称。

S​kill 初始化：S​kill 的入口文件被加载，仅把必需信息注入上下文，以免一次性塞满 token。

S​tep‑by‑Step 执行：S​kill 按照《Standard Workflow》章节指示逐步调用 scripts 或 external API。

Error Handling 与回退机制：每一步dou有明确错误码与友好提示，防止模型陷入死循环。.

Result Aggregation:Zui后将所有子结果合并为统一输出，并返回给主 Agent。

references/ 目录相当于 Skill 的「百科全书」，每个 .md 文件dou围绕一个细分业务展开。例如：

conventional‑commits.md ：介绍 Git 提交规范；

language‑specific.md ：列举不同编程语言下的Zui佳实践；

project‑types.md ：提供 Web、CLI、微服务等项目模板。

在 SKILL.md 中，只需要写一句类似 「参见 references/conventional‑commits.md 获取完整提交规则」 的链接文字即可，保持主文件轻盈且易读。

**统一编码**：所有文本使用 UTF‑8，无 BOM；

**Token 限制**：单个 SKILL.md 建议控制在 800 行以内，以免占满模型上下文；

**避免硬编码路径**：脚本内部应通过环境变量或配置文件读取资源路径；

**审计日志**：每一次对外调用dou必须记录输入/输出摘要，以便事后追踪。

1️⃣ 把所有实现细节直接写进 SKILL.md —— 会导致上下文膨胀，模型难以聚焦核心逻辑。 2️⃣ 使用随意命名的字段 —— 搜索引擎无法索引，也会让协作者产生歧义。 3️⃣ 忽视错误处理 —— 一旦脚本抛异常，整个对话链路就会卡死。 4️⃣ 将参考文档堆砌在根目录 —— 随着项目 ，这种扁平结构hen快失控。

/ # 假设Yi经 clone 项目到本地
cd my-skill
./scripts/run.py --input "提取 PDF 中所有表格"
# 完成后模型会返回 JSON 格式结果

只需要复制上述命令，即可感受一次完整调用链路，从意图捕获到结果返回全部自动完成。

该 Skill 用来帮助开发者生成符合 Conventional Commits 标准的提交信息。核心思路如下：

User 输入：「提交一个修复登录错误」；

Skill 根据 keywords 匹配到 references/conventional‑commits.md；

脚本 generate_commit.py 自动生成 `fix: 修复登录错误`；

validate_commit.py 检查长度与格式是否合规。

这里不展示具体代码，只强调了「读取 reference → 调用 script → 返回校验结果」这三个关键步骤，使得整个流程清晰且易于迁移到其他语言或平台。

构建一套标准化的智Neng体技Neng，就像为团队装上一把精准定位的指南针。从目录布局到元数据约束，再到工作流编排，每一步dou值得仔细雕琢。只要坚持以上原则，你会发现过去繁琐的手工操作瞬间被自动化取代，而团队成员也因为统一语言而沟通geng顺畅。

现在就挑选一个业务场景，把本文提供的骨架拷贝过去，填入自己的业务描述与脚本，实现第一条可运行的 Skill 吧！成功之后你会惊喜地发现——原来标准化并不枯燥，它Ke以像拼图一样带来成就感，也Neng让 AI 真正成为生产力的一部分。