企业官网建设流程全解析

这次我们来看一个 AI Agent 生态里出现频率快速上升的概念：Skill。如果你最近关注过 Claude、Codex 或者 Cursor 的更新，大概率会看到SKILL.md、Agent Skills这类名词；在不少 Agent 框架的规划里，Skill 也已经和 Tool、MCP 一起，被当作 Agent 能力拼图中独立的一块。

在动手写复杂的 Agent 工作流之前，先把 Skill 是什么、它解决什么问题、和 Plugin / Function Calling / MCP 有什么区别讲清楚，后面做工程才不会跑偏。这篇是系列教程的第 01 篇，内容覆盖概念、目录结构、一个能跑通的完整示例，以及 Skill 的加载与调试思路。下一篇再讲如何批量设计和管理一套 Skill 体系。

先说结论：Skill 本质上是一份“给 Agent 的操作手册”。它把模型默认不知道的专业流程、企业规范、手工操作步骤，打包成一个带触发条件的指令包。Agent 判断当前任务和某个 Skill 相关时，就把这份手册加载进上下文，照着执行。和传统插件最大的差异在于，Skill 的核心是“流程知识”，而不是“可调用的外部函数”。

1. 核心能力速览

需要说明：以上是 Skill 这套通用机制的能力边界。具体到某个产品，目录位置、导入方式和字段命名要以官方文档为准。本文后面的示例会统一使用当前公开资料里最通用的写法。

2. 什么是 AI Skill：概念与价值

先看一个具体场景。你用 Claude 或 Codex 写完代码，想让 Agent 做一次规范的项目复盘。默认情况下，模型只知道“复盘”这个词的通用含义，不知道你团队要求的模板、字段、评分标准、输出格式。传统做法是在每次提问时把一长段要求粘贴进提示词框，或者在系统提示词里写死一大段规则。前者每次都重复劳动，后者会让无关任务也背上这部分上下文开销。

Skill 解决的就是这个问题。它让你把“项目复盘怎么做”这套流程固化成一个文件夹，里面有一份SKILL.md，描述清楚“什么情况下用、按什么步骤做、输出什么格式”。Agent 判断当前请求与这份描述匹配时，自动把流程加载进上下文并按步骤执行。用户不需要在每次对话里重新解释规则，Agent 也不需要无差别地长期持有这些规则。

从公开资料和社区实践看，Skill 的价值主要体现在三个层面：

第一是流程可复用。一个团队可以把独有的开发规范、代码审查清单、发布检查步骤做成 Skill，同一个仓库、同一个项目组共享。新人上手时，Agent 自动携带团队经验，而不是靠师傅口头传授。

第二是提示词工程的可维护性。过去调试一长串 system prompt 很痛苦，改动一个环节就要整体测试。Skill 把流程拆成独立单元，改一个 Skill 不影响其他功能，也方便做版本管理。

第三是约束 Agent 的输出行为。Skill 里可以写死“必须输出哪些字段”“禁止做哪些操作”，比在对话里临时叮嘱稳定得多。尤其是涉及合规、安全、格式要求的场景，用 Skill 固化规则比依赖模型自觉可靠。

需要提醒一个常见的概念混淆：中文互联网搜索“Skill”会出现很多无关内容，比如游戏技能、个人技能提升，甚至一些不良内容。本文讨论的 Skill 特指 AGI / Agent 领域的技术概念，即 OpenAI、Anthropic 等公司及其生态社区定义的 Agent Skills。后续看到SKILL.md、Agent Skill、skill pack这类词，都应该按这个技术含义理解。

3. Skill 与 Plugin、Function Calling、MCP 的边界

Skill 刚流行时最容易踩的坑，就是把它和 Plugin、Function Calling、MCP 混为一谈。这四者确实都服务于“让 Agent 更强”，但解决的问题完全不同。

Plugin 是应用层扩展。它直接给宿主软件增加新功能，比如编辑器里加一个主题插件、浏览器里加一个翻译插件。Agent 领域的插件往往意味着新的界面入口或功能模块。Skill 不改变应用本身的功能，只是给模型提供一套执行任务的指令。

Function Calling / Tool 是能力接入。模型通过函数调用去执行一段真实代码，获取计算结果或操作外部系统。它是“执行动作”的通道，模型自己没有这条通道时什么都干不了。Skill 里也可以包含脚本，但脚本只是辅助确定性步骤，Skill 的主体仍然是流程指南。

**MCP 是工具接入的标准化协议。**它解决的是“每个工具都自己定义接口格式，Agent 接起来太累”的问题。MCP 统一了工具描述、调用、返回的格式。Skill 和 MCP 可以共存：MCP 负责把外部能力变成标准工具，Skill 负责教 Agent 如何组合使用这些工具完成一套复杂流程。

最直观的理解方式：MCP 给 Agent 提供了“能用的零件”，Skill 给了“装配手册”。一份好的 Skill 里，完全可以描述“先用 MCP 的文件工具读取代码，再按清单逐条审查，最后用 MCP 的文档工具生成报告”。两者不冲突，反而经常一起出现。

4. Skill 的标准结构：目录、SKILL.md、脚本与资源

目前主流 Agent 产品的 Skill 实现虽然细节不同，但目录结构高度相似。一个标准的 Skill 通常是这样的：

my-skill/ ├── SKILL.md ├── scripts/ │ └── validate.py └── assets/ └── checklist.md

SKILL.md是唯一必需的入口文件。它负责声明 Skill 的基本信息和执行流程。文件头部有一段 YAML frontmatter，至少包含name和description两个字段：

--- name: python-code-review description: 对 Python 代码进行系统化审查。当用户请求代码审查、寻找 bug、做重构建议时使用。 ---

• name是这个 Skill 的唯一标识，通常是短横线连接的小写英文，比如python-code-review。不同 Skill 的 name 不能重复。
• description是触发判断的关键。Agent 拿到用户请求后，会和各 Skill 的 description 做语义匹配。匹配到才加载整个 Skill。

SKILL.md的正文部分用来描述完整的执行流程。一般按“使用时机 -> 操作步骤 -> 输出格式 -> 注意事项”组织。这部分内容会被加载进模型上下文，所以必须准确、精简、可执行。

scripts/目录放可执行脚本。当 Skill 里的某些步骤需要确定性计算时，可以写脚本让 Agent 调用。典型的例子包括：语法检查、文件批量重命名、数据格式转换。脚本不是必须的，纯提示词型 Skill 也可以正常工作。但脚本能弥补模型在精确计算上的短板。

assets/目录放辅助资源。包括参考文档、模板文件、checklist、示例图片等。Agent 执行流程时如果需要这些资源，可以从这里读取。这个目录可以避免把大段模板塞进SKILL.md撑爆上下文。

有一点必须强调：Skill 不是注册制。它不像浏览器插件有统一商店，也不像 MCP 有标准服务列表。主流做法是把 Skill 文件夹放到指定目录（如项目的.claude/skills/或仓库的.codex/skills/），或者从 URL 导入。具体目录位置和分发机制，每个产品有自己规定，以官方文档为准。

5. 创建第一个 Skill：从零到可用的完整示例

下面创建一个“Python 代码审查”Skill，演示从目录创建到实际可用的完整过程。这个示例适合任何在本地做过 Python 开发的人直接测试。

5.1 创建目录结构

先按目标产品的要求创建目录。这里以 Claude Code 项目级 Skill 的常见目录.claude/skills/为例：

mkdir -p .claude/skills/python-code-review/scripts mkdir -p .claude/skills/python-code-review/assets

如果是 Codex 项目，习惯上是放到仓库里的.codex/skills/路径。目录创建的思路一致，路径名需要按实际产品替换。

5.2 编写 SKILL.md

在python-code-review目录下创建SKILL.md：

--- name: python-code-review description: 对 Python 代码做系统化审查。当用户请求代码审查、寻找 bug、做重构建议、提交前检查时使用。 --- # Python 代码审查 ## 使用时机 - 用户要求审查单个 Python 文件或整个目录。 - 用户准备提交代码，需要提交前检查。 - 用户要求分析性能或安全隐患。 ## 审查步骤 1. 先读取目标文件或目录结构，确认代码入口。 2. 按以下维度逐项检查： - 正确性：边界条件、异常处理、空值处理； - 可读性：命名、函数长度、注释质量； - 性能：循环内重复计算、不必要的 I/O； - 安全：输入校验、命令拼接、依赖来源。 3. 如存在 assets/checklist.md，按清单逐项核对。 4. 输出结构化审查报告。 ## 输出格式 - 使用表格输出：| 文件 | 行号 | 严重级别 | 问题描述 | 修改建议 | - 严重级别分为 High / Medium / Low。 ## 注意 - 不直接重写用户代码，除非用户明确要求。 - 对不确定的问题给出判断依据，不要猜测。

这份SKILL.md写清楚了触发条件、执行步骤、输出格式和边界。Agent 在对话中遇到代码审查相关请求时，会尝试加载这份流程。

5.3 添加辅助脚本

在scripts/目录下放一个 Python 语法检查脚本，用于让 Agent 在审查前先做一轮确定性的语法校验：

#!/usr/bin/env python3 # scripts/check_syntax.py import ast import sys from pathlib import Path def check_file(path: Path) -> int: try: ast.parse(path.read_text(encoding="utf-8")) print(f"[OK] {path}") return 0 except SyntaxError as e: print(f"[ERROR] {path}:{e.lineno} -> {e.msg}") return 1 def main() -> int: files = list(Path(".").rglob("*.py")) if not files: print("no python files found") return 0 return max(check_file(f) for f in files) if __name__ == "__main__": sys.exit(main())

如果本机没有脚本执行权限，需要先加权限：

chmod +x .claude/skills/python-code-review/scripts/check_syntax.py

5.4 添加核查清单

在assets/目录放一份checklist.md，避免把过长内容写进SKILL.md主文件：

# 提交前核查清单 - [ ] 所有函数和变量命名是否清晰 - [ ] 是否有未处理的异常分支 - [ ] 循环内是否存在重复计算 - [ ] 是否使用了不安全的 shell 拼接 - [ ] 依赖是否写入 requirements 文件

5.5 验证 Skill 是否生效

完成以上步骤后，目录结构长这样：

.claude/skills/python-code-review/ ├── SKILL.md ├── scripts/ │ └── check_syntax.py └── assets/ └── checklist.md

启动 Agent，输入一句触发性需求，例如“帮我对这个项目的 Python 代码做一次提交前审查”。如果 Skill 配置正确，Agent 会在回答中按SKILL.md里定义的步骤和输出格式执行。判断生效的标志是：输出格式和你定义的表格结构一致，并且执行了脚本或引用了 checklist。

如果没有任何反应，优先检查description是否足够明确，以及目录是否放在了目标产品认可的路径下。

6. Skill 如何被加载、是否消耗上下文、如何调试

很多人在第一次使用 Skill 时会有一个疑问：它是不是一直在后台运行？答案是否定的。

Skill 的加载是按需匹配机制。Agent 每轮对话开始时，会拿到各 Skill 的name和description列表，在用户请求到来后进行语义匹配。匹配命中才把SKILL.md正文注入上下文；没命中就不加载。这也意味着：description写得好不好，直接决定 Skill 会不会被触发。

这里有一个常见的上下文开销陷阱。Skill 的元信息（name 和 description）通常会被 Agent 常驻持有，数量一多就会持续占用一定上下文空间。而匹配成功后加载的SKILL.md正文，会在执行期间占用大量上下文。因此设计 Skill 时有两个明确原则：

• description 要短而精准，方便 Agent 快速判断；
• SKILL.md 正文要精简到能完整执行流程，能放 assets 的绝不堆进主文件。

怎么确认 Skill 真的被加载了？不同产品的调试手段不一样，但通用的方法是看 Agent 的执行日志或回放记录。多数产品会在内部提示中写入类似“Loaded skill: python-code-review”这样的标记，或者在最终输出里体现 Skill 中定义的格式。如果你在测试中发现输出没有按 Skill 里的格式走，基本可以判断没有加载成功。

Skill 不触发时，按这个顺序排查：

1. 目录位置是否正确，文件名是否严格叫SKILL.md；
2. YAML frontmatter 是否有语法错误，name是否唯一；
3. description是否写得足够具体，包含用户会用的触发词；
4. 测试输入是否在 description 描述的语义范围内。

调试 Skill 是一个迭代过程。改 description、加具体触发词、重新测试，比一次性写一个完美的 Skill 更现实。建议每次只改一个变量，观察效果变化。

7. Skill 的部署与跨工具迁移

Skill 目前在生态里还没有一个统一的“应用商店”，部署方式仍然以目录和仓库为主。从社区实践看，主要有三种方式：

项目级部署。把 Skill 放在项目仓库内，跟随项目走。例如 Claude Code 常见的是.claude/skills/，Codex 常见的是.codex/skills/。这种方式适合团队统一规范，所有人 clone 仓库后 Skill 自动可用。

用户级部署。把 Skill 放在当前用户的全局配置目录下，对所有项目生效。具体路径因产品版本而异，建议以官方文档为准。这种方式适合个人高频使用的通用技能，比如日志分析、Markdown 排版规范。

URL 导入。部分产品支持从 URL 直接导入 Skill，本质上还是把远程的一个 Skill 文件夹拉取到本地目录。这种方式的优点是分发方便，缺点是安全风险更高，后面专门讲。

跨工具迁移时要注意格式差异。虽然 SKILL.md 的大结构趋同，但不同产品的 frontmatter 字段、目录路径、脚本调用约定可能不同。一个为 Claude Code 写的 Skill，直接复制到 Codex 下可能识别不了。迁移时做三件事：确认目标产品的 Skill 目录路径、检查 frontmatter 字段是否符合规范、用最简测试用例验证触发。

一个值得提前规划的点是版本管理。既然 Skill 以文件夹形式存在，天然适合纳入 Git 管理。建议每个 Skill 独立子目录，在仓库里统一管理。改动 SKILL.md 时写清 commit message，方便回溯是哪个版本引入的行为变化。

8. Skill 编写最佳实践

从公开资料和社区案例看，写一个“刚好能用”的 Skill 很容易，写一个“长期稳定、别人也好维护”的 Skill 需要遵循一些工程约束。这节给出当前实践中比较一致的几条建议。

一个 Skill 只解决一个流程。试图把“代码审查 + 报告生成 + 自动修复 + 沟通周知”全塞进一个 Skill，会让触发判断变得模糊。拆开后，每个 Skill 的 description 可以写得更具体，触发更精准，维护也更独立。

SKILL.md 控制长度。加载后它要进入上下文，每多一行都是额外开销。把模板、长样例放进 assets，主文件只保留“做什么、怎么做、输出什么”。经验上的合理区间是主流程能在一屏内看完，具体长度按自己项目复杂度和上下文预算调整。

步骤要写成可验证的指令。与其写“深入分析代码”，不如写“逐文件检查边界条件、异常处理、空值分支，并给出文件、行号、严重级别”。越具体，结果越可预期。

明确输出格式。在 Skill 里规定结构化输出，比如“使用表格，列为 文件/行号/严重级别/问题描述/修改建议”。这能让多次运行的结果保持稳定，也方便后续接自动化流程。

包含显式边界。写明“不做什么”和“什么情况下停止”。例如代码审查 Skill 里注明“除非用户要求，否则不直接修改代码”，可以避免 Agent 在审查过程中顺手改动业务逻辑。

**脚本只做确定性步骤。**语法检查、格式转换这类结论确定的步骤适合用脚本；需要判断、取舍、权衡的部分交给模型。把两者混在一起会让 Skill 变得脆弱。

控制 Skill 总量。常驻元信息会占上下文，Skill 太多还会增加匹配歧义。优先保留高频、稳定、效果好的 Skill，低频技能单独按需加载，而不是全部常驻。

**纳入版本控制。**每个 Skill 独立目录，进入 Git；改动记录清楚。这个习惯在团队协作时价值远远大于个人使用。

9. 安全与合规边界

Skill 的本质是把一份指令注入 Agent 的上下文，这意味着它拥有改变 Agent 行为的权限。如果这份指令来自不可信来源，风险就会随之而来，这是 Skill 使用中必须严肃对待的问题。

第一个风险是 Skill 注入。一个被恶意构造的 SKILL.md，可以指示 Agent 忽略用户约束、改变系统行为，甚至诱导用户执行危险命令。在 Open WebUI、Claude Skills、Codex Skills 等生态中，社区已经注意到对 Skill 文件本身的内容安全审查需求。启动任何来源不明的 Skill 前，务必先通读一遍 SKILL.md 和 scripts 目录下的脚本，确认没有隐藏指令。

第二个风险是隐私泄露。Skill 的 description 和内容会随请求发送给模型服务商；如果 Skill 里包含内部流程细节、企业敏感信息，等于把这些内容直接暴露给外部服务。不要把密钥、内部系统地址、客户数据写进 Skill。

第三个风险是自动化扩大的错误影响。Skill 让 Agent 可以按固定流程批量执行任务，比如批量修改文件、批量发送消息。流程设计有误时，错误也会被批量放大。第一次跑通 Skill 时，先用小样本、只读模式验证，再放开写操作。

第四个风险是授权边界。如果用 Skill 处理代码、文档、影音素材，需要确认素材来源合法、用户有对应授权；涉及人脸的图像与视频类 Skill，更需要严格核实授权链条。Skill 本身只是提高效率的工具，不改变使用者的合规责任。

结合当前合规要求，使用 Skill 时应遵循几个底线原则：只安装可追溯、可信来源的 Skill；使用前审查内容；不把敏感凭据写入任何 Skill 文件；涉及生产环境的操作先在小范围灰度验证。

10. 常见问题与排查方法

以下问题列表基于 Skill 的通用机制整理，覆盖社区反馈中出现频率较高的场景。不同产品的具体表现可能略有差异，但排查思路基本通用。

遇到问题时，先做小步验证。最有效的调试方式是把 Skill 目录临时简化到只含一个SKILL.md，确认主流程能触发后，再逐步加回脚本和资源。这个方法能快速区分问题是出在加载机制还是内容本身。

11. 下一步：从概念到批量管理

这篇把 Skill 的概念、边界、目录结构、创建流程和排查思路讲完了。对读者来说，最有价值的下一步不是立刻写很多个 Skill，而是先做一次“验证循环”：

在你的目标 Agent 产品里，按 5.1 到 5.5 的步骤创建一个最简 Skill，用一个小请求确认触发生效；然后基于这个验证过的格式，逐步沉淀自己团队或个人的高频流程。把验证标准、触发词、输出格式在每个 Skill 里写清楚，维护成本会低很多。

后续教程会继续展开三块内容：一是多个 Skill 之间的组织与管理，包括命名规范、目录层级、共享与版本发布；二是 Skill 中脚本的进阶用法，如何与 MCP 工具组合完成复杂任务；三是针对具体场景的 Skill 案例拆解，例如文档解析 Skill、批量数据处理 Skill 和代码仓库治理 Skill。

Skill 是一个门槛很低但工程上限很高的概念。不需要会写复杂代码就能入门，但要把一套 Skill 体系做到稳定、安全、可复用，需要投入设计和测试。建议收藏备用，也欢迎在评论区留下你实际测试中遇到的报错现象，后面案例篇会针对高频问题做专题排查。