企业官网建设流程全解析

第一次接触Claude Code和Codex的人，往往都会被一种能力震撼：你给它一个任务，它能自己读文件、跑命令、修代码，像一个不知疲倦的同事。但用上一两周，新鲜感过去了，很多人会陷入同一个困惑：为什么每次让它做一个类似的任务，它都像第一次接手一样，从零开始问东问西，甚至犯同样的错误？这不是模型退化了，而是你的使用方式还停在“临时对话”阶段。我今天想和你聊的Agent Skills，就是解决这个问题的一套方法论。它能让你把AI的零散能力，沉淀成可复用、可扩展、可维护的技能体系。这篇文章不是纯概念科普，我会带着你从场景出发，一步步理解它，并且结合Claude Code和Codex，跑通一个最小可用技能。

1. 先用一个具体场景理解Agent Skills在解决什么

1.1 每天都在做重复描述，这不是AI的错

假设你负责一个Python项目，团队约定过一套代码规范：变量明明要清晰，函数不能太长，关键路径要有注释。每次你让Claude Code做代码审查，都要在对话框里重新说一遍：

“请检查一下项目中src目录下的Python文件，忽略test目录，重点看风格问题，输出按严重程度分级的报告。”

第一次用很爽，AI很快给出报告。第二次、第三次，你开始不耐烦了。为什么同一个团队、同一个项目、同一套规范，每次都要重新打一遍？更麻烦的是，如果团队里有五个人，每个人打出来的描述都不一样，AI给出的结果也不完全一致。有人让它看“代码风格”，有人让它看“潜在Bug”，有人让它“随手优化一下”，最后你根本没法横向比较。

这并不是AI不聪明，而是你只把它当成一个临时对话对象。模型没有项目记忆，也没有一个稳定的岗位说明书。每次对话开始，它对你的项目规范、输入格式、输出要求都一无所知。它只能靠你那几句零碎描述临场发挥。

Agent Skills解决的核心问题，就是把这段“每次都要重复描述的对话协议”固化成文件。它不再依赖你现场发挥，而是让AI在需要的时候，自动读取一份规范文档，按里面的流程执行。

1.2 Agent Skills不是插件，也不是简单的预设提示词

有人第一次听到Agent Skills，会把它想象成浏览器插件：装上一个，AI就多一个功能。也有人觉得，这不就是预设提示词吗？预先写一段话，让AI照着做。

其实两者都不是。

一个标准的Agent Skill，可以理解成一张“岗位说明书 + 操作手册 + 工具清单”的合订本。它一般包含：

• 一个用Markdown编写的SKILL.md文件，描述这个技能是做什么的、什么时候该用、输入是什么、输出是什么、执行流程是什么、有什么限制。
• 一个或多个辅助脚本，用来执行具体动作，比如运行测试、扫描代码、生成文档。
• 可能还包括模板、配置文件、参考例子等资源。

相比普通提示词，Skill最大的区别是：提示词只是一段话，用完就没了；Skill是一个“微型项目”，它有自己的目录结构、版本、依赖和验证方法。正因为它是项目，你才能持续维护它、测试它、分享给团队成员，也才能让不同的Agent稳定复用它。

1.3 核心判断：Agent Skills的价值在于“工作流固化”

所以我的核心判断是：Agent Skills真正解决的，不是让模型多会一个功能，而是把“一次性的人机对话”变成“可持续积累的工程资产”。

过去我们想约束模型行为，通常靠写一大段system prompt，或者每次对话里塞入few-shot示例。但在Claude Code、Codex这类命令行Agent场景里，prompt如果太长，会占用大量上下文窗口；如果太短，又约束不住模型行为。Agent Skills提供了一种新的注入方式：它把提示词和脚本都放在项目目录里，Agent遇到相关任务时按需加载。需要的时候才读取，不需要的时候完全不打扰主对话。

这带来的变化是结构性的。你不再靠记忆力让AI保持一致，而是靠文件系统、目录规范、版本管理来保证一致性。AI的行为开始变得可复现、可监督、可改进。

2. 拆开一个Agent Skill：SKILL.md里到底该写什么

2.1 技能包的目录结构

在Claude Code中，一个技能通常被放在项目的.claude/skills/目录下，每个技能使用一个独立子目录，核心文件叫SKILL.md。常见结构如下：

.claude/skills/my-skill/ ├── SKILL.md └── scripts/ └── check.py

在最简单的情况下，你只需要一个SKILL.md，里面写清楚做什么、怎么做。如果技能需要跑脚本或参考数据，再补充scripts/、templates/等目录。

在Codex等工具中，类似机制可能表现为AGENTS.md或项目级指令文件。不同工具的载体不同，但设计思想是一致的：用人类可读、机器也能理解的结构化文档，把任务流程描述清楚。

2.2 SKILL.md的内容框架

一份能稳定复用的SKILL.md，至少要包含下面这些信息：

• name：技能名称。要短、唯一、易检索。不要叫“最好用的技能”，而要叫python-lint-check。
• description：一句话说清楚技能解决什么问题，并明确触发条件。例如“当用户要求执行Python代码风格检查、提交PR前质量检查时使用”。
• 适用场景：什么情况下该调用，什么情况下不该调用。
• 输入要求：技能执行前需要哪些参数或信息，比如“目标目录”“忽略文件列表”。
• 输出规范：AI完成后应该返回什么，是报告、文件、还是修改记录，格式如何。
• 操作流程：一步一步的行动指令，让AI按顺序执行。
• 依赖与限制：需要的软件环境、包依赖、可用命令，以及对危险操作的禁止项。

下面是一个简化的SKILL.md示例，用于Python代码风格检查：

--- name: python-lint-check description: 对项目中的Python文件执行PEP8风格检查，输出分级报告。当用户要求做代码风格审查、质量检查时使用。 --- # Python Lint Check ## 使用场景 - 用户要求检查Python代码风格或质量。 - 用户准备提交PR，需要先做自查。 ## 不适用场景 - 用户只是想修改某个文件的逻辑，不需要完整报告。 - 项目中不存在Python代码。 ## 输入 - target_dir: 要检查的目录，默认为当前目录。 - ignore_files: 需要忽略的文件列表，可选，用逗号分隔。 ## 执行步骤 1. 确定待检查目录，确认其中存在 Python 文件。 2. 使用 scripts/check.py 执行检查，传入 target_dir 和 ignore_files。 3. 将脚本输出整理为 Markdown 报告，按 Error / Warning / Info 分组。 4. 若脚本退出码非0，列出最严重的几条，并给出修复建议。 ## 输出格式 返回 Markdown 报告，包含： - 检查范围 - 发现的严重问题 - 改进建议

2.3 为什么用Markdown而不是JSON或YAML

可能你会问：为什么不用JSON结构，然后由程序解析？

原因在于，Agent Skills的主要读者是AI模型，不是传统程序。模型读Markdown，就像人读一份排版清晰的文档，理解门槛低；而JSON虽然结构化，但对模型来说，描述复杂执行逻辑时反而不直观。尤其是“如果出现某种情况，应该怎么处理”这种带分支的指令，用自然语言加列表写出来，效果远好于嵌套JSON。

另外，Markdown天然支持代码块、表格、引用、步骤列表，方便同时容纳说明、命令、示例和约束。任何一个会写Markdown的开发者，都能快速上手维护技能。这也是Agent Skills普及速度比插件生态更快的原因之一——你不需要学一套SDK。

3. 在Claude Code里跑通你的第一个Agent Skill

3.1 准备环境

在开始之前，假设你已经安装了Claude Code CLI。如果还没安装，常见方式是通过npm或包管理器安装。例如：

npm install -g @anthropic-ai/claude-code

不同版本和安装方式以官方文档为准。安装完成后，在项目根目录运行claude进入交互界面。

有一个容易被忽略的点：CLI启动后，需要能正常连接模型服务。如果这一步不通，后面所有操作都无法继续。你可以先随手问一个简单问题，确认模型能正常响应，再进行技能开发。

3.2 创建第一个技能：代码规范审查

我们做一个简单但高频的技能：代码规范审查。目录结构如下：

.claude/skills/code-review/ ├── SKILL.md └── scripts/ └── review.py

这里以一个小脚本为例，演示技能如何调用外部命令。假设我们使用pylint做检查：

#!/usr/bin/env python import subprocess import sys target_dir = sys.argv[1] if len(sys.argv) > 1 else "." result = subprocess.run( ["python", "-m", "pylint", target_dir], capture_output=True, text=True, check=False, ) print(result.stdout[-2000:]) # 只打印关键部分，避免输出过长

然后把刚才的SKILL.md填入SKILL.md文件。记得给脚本可执行权限：

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

3.3 调用技能与验证

在Claude Code中，你可以直接对话说：

请对src/目录执行代码规范审查

如果技能设计合理，Claude Code会自动关联到code-review技能，读取SKILL.md，然后调用脚本完成任务。如果自动匹配失败，你也可以用斜杠命令显式调用：

/code-review src/

验证技能是否生效，不能只看AI说自己“使用了技能”。更可靠的办法是看它的执行过程：它有没有读取SKILL.md？有没有运行脚本？输出结果是否符合作业要求？

3.4 常见坑：技能目录没被加载、上下文溢出、脚本权限

实际踩坑过程中，这几点出现频率最高：

• 路径放错：技能必须放在.claude/skills/下面，不是普通的skills/目录。
• 文件名写错：核心文件必须叫SKILL.md，大小写要一致。
• 命名不规范：技能名不要带空格或特殊符号，否则容易被当成路径的一部分。
• 描述太泛：AI不知道什么时候触发。描述越具体，匹配越准确。
• 上下文溢出：SKILL.md写了几百行细节，AI一读上下文就满了。这会让技能难以被正确执行。更好的做法是，SKILL.md只写主流程，详细规则放在附件的独立文档里，按需读取。
• 权限问题：脚本没有执行权限，或者依赖包没装。技能脚本最好先在终端手动运行一遍，确认无误再交给AI。

判断技能是否生效，不能只听AI说自己“使用了技能”。更可靠的方式是让它先输出技能的读取过程，或者在技能脚本里打印日志。

4. 再看Codex：不同工具如何对待Agent Skills

4.1 Codex也有项目指令机制，但不叫Skill

OpenAI的Codex CLI是另一款常用的命令行AI编程工具。它的核心工作方式也是让AI在终端里读写文件、执行命令。Codex中项目级指令通常通过AGENTS.md来组织，里面可以写项目背景、常用命令、代码规范等。

从定位上看，AGENTS.md更像是Claude Code的CLAUDE.md，属于“项目记忆文件”，和Agent Skills并不完全等价。但反过来想，我们可以把成熟的技能流程抽象出来，转写成AGENTS.md中的章节，让Codex也能照着执行。

也就是说：Agent Skill的概念本身跨工具成立，但每种工具装载这份技能的“容器”不同。

4.2 跨工具复用的三种做法

如果团队同时使用Claude Code和Codex，想让同一套流程两边都能用，常见做法有三种：

1. 复制粘贴法：把SKILL.md的核心步骤粘贴到AGENTS.md的某个章节。优点是简单直接，缺点是两边内容可能失步。
2. 转换脚本法：写一个小工具，从SKILL.md自动生成AGENTS.md片段或CLAUDE.md片段。适合技能数量多、需要频繁更新同步的情况。
3. 基于MCP的服务化：把技能涉及的脚本封装成MCP工具，让不同Agent通过统一接口调用。但需要说明，MCP更擅长“工具接入”，技能的编排逻辑还是需要由Agent侧的文档来引导。

我的建议是：如果项目只用一个AI工具，优先用原生Skill机制；如果多个工具混用，先不要急着搞自动化转换，先在团队里建立一份“Agent工作流规范”，保持单一信息源，再手动或半自动映射到各工具文件。

4.3 不要被工具绑架，技能的核心是“流程”

观察Claude Code和Codex的演化，你会发现一个趋势：AI编程工具正在从“聊天生成代码”走向“可配置的自动化执行环境”。

在这种环境里，模型的能力大同小异，真正的差异在于你如何定义任务、如何组织上下文、如何约束行为。SKILL.md也好，AGENTS.md也好，它们的本质都在回答两个问题：这个Agent能做什么？它应该怎么做？

所以，你在设计技能时，不要只盯着某个工具的语法。先把工作流程本身写清楚：输入是什么，输出是什么，先做什么，再做什么，遇到异常怎么办。工具语法变了，这套流程依然成立。

5. 从单个技能到技能体系：工程化的五个阶段

5.1 以复用为目的，而不是以“写出来”为目的

很多人在创建第一个技能时，容易犯“求大求全”的毛病。恨不得把一个完整需求从设计到测试全部塞进Skill里。结果AI读一下SKILL.md就把上下文占满了，执行起来总是半途而废。

正确的开启方式是从小任务开始。推荐五个阶段：

1. 选一个高频、低风险、可验证的任务。
2. 先以普通对话的方式跑通一次，记录下哪些步骤是有效的、哪些描述会产生歧义。
3. 把有效的步骤固化成SKILL.md。
4. 用几个不同的输入样例测试技能，看它是否稳定。
5. 稳定之后，再考虑和其他技能组合，形成更复杂的自动化流程。

5.2 技能命名和目录组织

当技能数量超过五个，就需要维护一套组织规范。下面是一个示例结构：

.claude/skills/ ├── code-review/ ├── test-runner/ ├── docs-generator/ └── changelog-updater/

命名建议使用小写字母加中划线，简洁明了。每个技能目录里可以加一个README.md，记录技能的用途、维护人和变更记录。如果使用Git管理，技能应该和代码一起提交，这样团队其他人拉下代码就能共享同一套技能。

5.3 技能版本与依赖管理

技能一旦涉及脚本，就会有依赖。比如需要Python 3.10、需要安装pylint、需要某个环境变量。这些信息必须写在SKILL.md里，最好单独列一个“依赖”小节：

## 依赖 - Python 3.10+ - pip install pylint - 建议在项目根目录的 .venv 虚拟环境中运行

对技能本身也要建立验证清单。每次修改SKILL.md或脚本，都固定跑一遍冒烟测试，确认输出格式符合预期。如果技能会修改文件，务必在测试目录或临时分支里试运行，不要上来就操作生产数据。

5.4 组合技能的编排思路

复杂任务往往需要多个技能协作。比如“发布一个新版本”，可能包含“运行全部测试”“更新版本号”“生成变更日志”三个步骤。在Claude Code中，模型可以根据用户意图动态编排技能调用顺序。

为了让技能之间能够协作，每个技能要保持“单一职责”。它只做一件事，并把结果输出成清晰的文本或结构化数据，方便另一个技能把它当作输入。比如“运行测试”技能输出测试通过/失败状态，“生成变更日志”技能就可以根据这个状态决定是否继续。不要在一个技能里塞进全部逻辑。

6. 排查链路：当技能不按预期工作时怎么办

6.1 先分层定位

技能出问题时，不要急着改提示词。先按下面这个链路定位问题在哪一层：

1. 看现象：是完全没被触发，还是触发了但执行结果不对？
2. 看技能文件：SKILL.md是否在正确目录？文件名对不对？Markdown格式是否完整？
3. 看技能描述：description是否包含了足够的触发词？会不会和其他技能描述冲突？
4. 看依赖：脚本路径是否正确，有没有执行权限，依赖包有没有安装。
5. 看上下文：对话历史是否太长，导致技能描述被截断或忽略。
6. 看模型行为：有些模型会跳过技能直接回答，这时可以尝试显式指定技能名称。

6.2 一个排查表格

6.3 为每个技能准备一条冒烟测试

无论技能多简单，都建议准备一条固定的测试指令，例如：

在examples/sample.py上执行code-review技能，确认输出包含Error和Warning分组。

把这条指令记录在技能的README里。以后每次修改技能，先跑冒烟测试，再谈优化。这相当于给你的Agent技能加了一组“单元测试”，能极大降低长期维护成本。

不要等到技能上线之后才测试。每改一次SKILL.md或脚本，都要在隔离的样例上验证一遍，确认行为没有悄悄漂移。

7. 适用边界与长期建议

7.1 什么场景值得做Agent Skills，什么场景不值得

值得做Agent Skills的场景有几个特征：

• 流程稳定：同一个任务每周至少碰到一次。
• 规则明确：输入输出格式固定，执行步骤清楚。
• 可验证：任务完成质量可以被明确判断。
• 有团队复用价值：不是只有你自己用，其他人也能受益。

不适合做Agent Skills的场景也很明显：

• 一次性的创意任务，比如“写几句广告语”。
• 规则经常变动，每次都需要重新设计的任务。
• 高风险操作，比如直接操作生产数据库。
• 上下文极长且边界模糊的任务，一个技能很难覆盖所有变化。

7.2 隐私与安全边界

技能本质上让AI按照你写好的流程读取文件、执行命令。因此技能本身也是攻击面：

• 不要随意从网上下载不明来源的Skill塞到项目里，除非你逐行审阅过。
• SKILL.md和脚本中不要写真实密钥、内部Token等敏感信息。
• 如果技能会执行Shell命令，尽量限制命令范围，禁止无差别删除文件。
• 团队共享技能前，把技能内容当代码一样做评审。

这些不是危言耸听。当技能生态越来越丰富时，恶意技能完全可能伪装成“开发辅助工具”，诱导AI执行危险命令。你要像对待第三方库一样对待第三方Skill。

7.3 长期来看，Agent Skills会带来什么变化

从“会用AI”到“会开发Agent”，真正的分水岭，是你有没有把AI的能力沉淀成团队共有的资产。

今天你只是给Claude Code写了一个代码审查技能；明天你可能会把项目规范、部署检查、文档生成、发布流程都逐步沉淀成技能库。当这些技能被集中管理和版本控制时，AI就不再是一个“偶尔聪明的实习生”，而是一个“熟读团队规范的老成员”。

我带过不少开发者使用这类工具。一个很明显的规律是：那些持续维护技能库的人，AI使用效率会越来越高；而那些每次都靠临时对话“现编”的人，过几个月还停留在最初的水平。差别不在模型能力，而在你是否愿意把一次成功经验，变成一套可持续复用的流程。

所以，我建议你从今天手头最重复、最烦人的任务开始。不要追求一次性做出一个大而全的技能，先做一个能解决当下问题的最小版本，然后真正去用它、改它，让它成为自己工作流的一部分。这个动作看起来很小，但坚持半年之后，你会发现AI的使用方式真的不一样了。