企业官网建设流程全解析

实际接手 Agent 开发后，很多人会发现一个转折点：会用 AI 写 prompt，和能把 AI 变成稳定执行任务的 Agent，中间隔着一层能力封装。Agent Skills 正是这一层封装的重要组成部分。简单说，Agent Skills 是一套可复用的技能包，它把某个场景下的指令、流程、脚本和模板打包起来，让 Claude Code、Codex 这类命令行 Agent 在遇到对应任务时，不再从空白对话开始，而是按预设流程执行。下面所有示例都偏向最小闭环，读者可以在自己的项目里按需替换。

1. 先理解 Agent 与 Agent Skills 的边界

在动手安装工具和写技能之前，先把概念边界弄清楚，否则很容易把 Agent Skills 做成一个普通的 Markdown 文件，既看不出效果，也找不到维护价值。

1.1 Agent 不是聊天机器人，而是有工具使用能力的执行体

聊天机器人的核心能力是“生成文本”，输入一段问题，输出一段回答。Agent 则是在文本生成能力之上，增加了“感知环境、拆解任务、调用工具、观察结果、调整计划”的执行循环。

一个典型执行循环可以拆成四步：

1. 收到目标：例如“把项目里所有 TODO 按优先级整理成文档”。
2. 拆解计划：先找出 TODO 出现在哪些文件，再判断优先级规则，再决定输出格式。
3. 调用工具：用 grep 搜索文件，用 cat 查看上下文，用脚本统计数量，最后写入文档。
4. 观察反馈：读取命令执行结果，判断是否完成；如果没有完整覆盖，继续补充处理。

关键区别在于“行动 + 反馈”。聊天机器人只能给出建议，Agent 可以直接读取项目文件、执行命令、修改代码。Claude Code 和 Codex 之所以被称为 Agent，就是因为它们具备这些工具调用能力，而不是简单地在终端里模拟对话。

1.2 Agent Skills 是给智能体补充的可复用能力包

Agent Skills 是一组“能力文件”的集合，通常包括说明文档、示例、脚本和模板。它的作用不是写一段 prompt，而是把某个场景下的完整操作手册打包给 Agent。

可以把它理解成给新员工的操作手册，而不是一句“好好干活”的叮嘱。操作手册里会写明：

• 什么情况下使用这个技能。
• 执行这个技能需要哪些前置条件。
• 操作分几步，每一步做什么。
• 哪些命令可以复用，哪些文件需要修改。
• 输出结果长什么样，怎么验证成功。

Agent 在对话中遇到匹配任务时，会读取这份操作手册，再结合当前项目上下文执行。

直接给 Agent 写 prompt 也能完成一次任务，但缺点非常明显：每次都要重复描述流程，团队里不同人的写法不一致，沉淀不了经验。Skill 把流程固化成文件，可以跨项目复用，可以用 Git 管理版本，可以像代码一样评审和测试。

1.3 Claude Code 与 Codex 在技能体系里承担什么角色

Claude Code 是 Anthropic 推出的终端开发 Agent，能够在代码库中完成多步开发任务。较新的版本会读取项目级或用户级技能目录中的技能文件，只要技能目录和说明文件符合约定，Claude Code 就能在对话中自动加载。

Codex 是 OpenAI 推出的命令行开发 Agent，更偏向代码生成、仓库理解和自动化修改。它的项目上下文通常依赖 AGENTS.md 这类指令文件，同时可以直接执行外部命令或脚本。

在技能体系里，这两个工具都扮演“执行器”角色：

• Agent 负责理解用户意图。
• 技能负责定义“遇到什么任务走什么流程”。
• 脚本和模板负责承载具体能力。
• 执行器负责把流程变成实际命令。

所以设计技能时，尽量不要让技能文件依赖某一个 Agent 的私有能力。技能的核心应该是一段清晰的任务说明和一个可执行的脚本入口。这样同一份技能就能在 Claude Code、Codex，甚至其他支持自定义指令的 Agent 工具之间复用。

2. 环境准备：装好 Claude Code 与 Codex，并验证可用

要跑通后面的技能示例，先把两个命令行 Agent 装好。这部分的坑其实比技能本身更多，尤其是路径问题和版本问题，经常让技能在一个工具上正常、在另一个工具上报错。

2.1 安装 Claude Code 的两种常见方式

Claude Code 依赖 Node.js 环境，建议先确认本机 Node.js 版本在 18 以上。如果版本过低，安装过程可能成功，但运行时会出现语法或兼容性错误。

常见安装方式是使用 npm 全局安装：

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

也可以使用官方提供的原生安装脚本或系统包管理器，具体命令以官方文档为准，因为安装方式会随版本迭代变化。

安装完成后，先不要急着进入对话，先验证一下可执行文件是否在 PATH 中：

claude --version

如果能输出版本号，说明安装成功。如果提示command not found，通常是 npm 全局目录没有加入 PATH。

2.2 安装 Codex 和第一道常见报错

Codex 同样可以通过 npm 安装：

npm install -g @openai/codex

也可以使用 Homebrew、包管理器或官方二进制包安装。安装完成后再验证：

codex --version

很多人在 IDE 插件里遇到的第一个报错是：

Unable to locate the codex CLI binary. Set codex CLI path or ensure the executable is in your PATH.

这个错误并不是技能问题，而是插件无法定位到 codex 可执行文件。常见原因有三个：

1. Codex 没有真正安装成功。
2. 安装成功但 npm 全局目录不在 PATH。
3. IDE 插件没有被允许读取终端环境变量，需要手动配置路径。

这一节先记住这个错误，第五节会给出完整排查链路。

2.3 用版本命令验证两个工具

安装完成后，建议用一组命令做环境检查：

claude --version codex --version which claude which codex

预期情况如下：

如果which没有输出路径，说明可执行文件不在当前 shell 的 PATH 中。此时需要把 Node.js 全局安装目录加入环境变量，或者在 IDE 中手动指定路径。

2.4 在 IDE 中配置 Codex 路径

如果使用 VSCode 或 Cursor 等编辑器里的 Codex 扩展，除了命令行的 PATH，还要注意 IDE 进程的环境变量不一定和终端一样。

常见的做法是在 settings.json 中指定 codex 路径：

{ "codex.cli.path": "/usr/local/bin/codex", "codex.cliPath": "/usr/local/bin/codex" }

不同版本插件的配置键名可能不同，有些使用codex.cli.path，有些使用codex.cliPath。另一种更通用的做法是设置环境变量：

export CODEX_CLI_PATH="$(which codex)"

然后在项目目录启动 IDE，让 IDE 继承这个环境变量。

环境检查清单：

• Node.js 版本是否满足要求。
• Claude Code 是否输出版本号。
• Codex 是否输出版本号。
• claude 和 codex 的绝对路径是否可见。
• IDE 扩展是否正确读取到 codex 路径。

3. 从零编写第一个可复用 Agent Skill

环境准备好之后，开始写第一个技能。这个技能选择“changelog-generator”，功能是根据 Git 提交历史生成 changelog。它适合演示技能开发的完整链路，因为流程清晰、输入输出容易验证，而且不依赖外部服务。

3.1 技能目录结构与命名规范

在常见 Agent 技能体系中，技能通常放在项目目录下的.claude/skills/或用户级技能目录中。技能名称建议使用小写字母和连字符，例如changelog-generator，避免使用空格和中文。

一个最小技能目录结构如下：

.claude/skills/changelog-generator/ ├── SKILL.md ├── scripts/ │ └── generate_changelog.py └── templates/ └── changelog.md

各文件职责如下：

技能目录的名称、SKILL.md 中的 name 字段、description 描述要保持一致。Agent 通过 description 判断什么任务能触发这个技能，如果 description 写得太模糊，Agent 很可能不会调用它。

3.2 写一个 SKILL.md 定义触发条件和使用说明

SKILL.md 是技能的入口文件。常见结构包含 YAML frontmatter 和 Markdown 正文。frontmatter 提供元信息，正文提供执行说明。

示例内容如下：

--- name: changelog-generator description: 根据 Git 提交记录生成标准化的 CHANGELOG.md，适合在发版前整理变更记录时使用。 --- # Changelog Generator ## 适用场景 需要把当前分支相对目标分支的提交记录整理成 changelog 时使用。 ## 执行步骤 1. 确定目标分支，默认是 main。 2. 运行脚本读取提交记录。 3. 按 Features、Bug Fixes、Documentation、Other 对提交分组。 4. 将结果输出到 stdout，由执行者决定是否写入 CHANGELOG.md。 ## 依赖 - git - python3 ## 使用示例 用户说：生成当前分支的 changelog。 执行者运行： python .claude/skills/changelog-generator/scripts/generate_changelog.py main

这里的关键点是 description。它应该描述“什么任务会用到这个技能”，而不是描述技能内部实现。Agent 拿到用户请求后，会把请求语义和所有技能的 description 做匹配。描述里最好出现“生成 changelog”“发布说明”“变更记录”等具体场景词。

3.3 用 Python 脚本实现核心逻辑

技能的核心逻辑放在脚本里，而不是全部写进 SKILL.md。这样既方便测试，又能让 Agent 通过一次命令拿到结构化结果。

示例脚本：

#!/usr/bin/env python3 """Generate a changelog from git commit messages.""" import subprocess import sys from collections import defaultdict def get_commits(base: str) -> list[str]: cmd = ["git", "log", f"{base}..HEAD", "--pretty=format:%s"] result = subprocess.run(cmd, capture_output=True, text=True) if result.returncode != 0: print(result.stderr, file=sys.stderr) sys.exit(1) return result.stdout.splitlines() def group_commits(commits: list[str]) -> dict[str, list[str]]: groups = defaultdict(list) for commit in commits: lower = commit.lower() if lower.startswith(("feat", "feature", "add")): groups["Features"].append(commit) elif lower.startswith(("fix", "bug", "patch")): groups["Bug Fixes"].append(commit) elif lower.startswith(("docs", "doc")): groups["Documentation"].append(commit) else: groups["Other"].append(commit) return groups if __name__ == "__main__": base = sys.argv[1] if len(sys.argv) > 1 else "main" commits = get_commits(base) if not commits: print("No commits found.") sys.exit(0) output = ["# Changelog", ""] grouped = group_commits(commits) for section in ["Features", "Bug Fixes", "Documentation", "Other"]: if section in grouped: output.append(f"## {section}") output.extend(f"- {item}" for item in grouped[section]) output.append("") print("\n".join(output))

脚本把结果打印到 stdout，而不是直接修改文件。这个设计是刻意的：让 Agent 决定最终如何写入文件，而不是脚本擅自覆盖项目内容。

本地可以直接验证脚本：

python3 .claude/skills/changelog-generator/scripts/generate_changelog.py main

如果当前分支相对 main 没有提交，输出为No commits found.。如果有提交，输出就是格式化后的 changelog。

3.4 在 Claude Code 中加载并测试技能

进入项目目录，启动 Claude Code：

cd /path/to/project claude

在对话中输入：

请使用 changelog-generator 技能，比较 main 分支和当前分支，生成 changelog 内容。

如果技能被正确加载，Claude Code 会读取 SKILL.md，然后调用脚本并整理结果。不同版本的界面提示不一样，有些会显示正在使用的技能名称，有些不会显示，但最终输出应该符合预期。

如果 Claude Code 没有调用技能，先检查：

1. 技能目录是否在正确位置。
2. SKILL.md 文件名是否准确。
3. frontmatter 是否包含 name 和 description。
4. description 是否包含“changelog”等触发词。
5. 当前 Claude Code 版本是否已升级到支持技能功能的版本。

4. 让同一份技能跑在 Codex 上

技能在一个 Agent 上跑通只是第一步。如果希望一份技能在 Claude Code 和 Codex 上都可用，需要理解这两个工具读取上下文的方式差异，然后做一个“低耦合”的技能设计。

4.1 Codex 与 Claude Code 对技能加载机制的不同

Claude Code 通过技能目录和 SKILL.md 来组织技能，遇到匹配任务时主动加载。

Codex 并不完全等价于 Claude Code 的 SKILL.md 机制。Codex 更依赖项目级指令文件，典型的是 AGENTS.md。AGENTS.md 会在 Codex 处理项目任务时被当作项目上下文读入，里面可以写明项目规范、可用命令和推荐工作流。

所以，想让一份技能在两个工具上复用，不建议只写一套私有格式，而是采用下面这种统一思路：

• 把“做什么、什么时候做”写进 SKILL.md，同时压缩成 AGENTS.md 中的一小段指令。
• 把“具体怎么做”全部封装到脚本里。
• 让 Agent 通过运行脚本来获得技能能力，而不是依赖某一种工具内置的技能渲染机制。

这种做法牺牲了一点自动化程度，但换来了跨工具的一致性和可测试性。

4.2 用 AGENTS.md 和入口脚本统一技能调用

在项目根目录创建 AGENTS.md：

# 项目指令 ## Skill: changelog-generator 当用户要求“生成 CHANGELOG”“整理发布说明”或“查看本次变更记录”时，使用 changelog-generator 技能。 执行方式：运行以下脚本并读取 stdout，再把结果整理给用户。 python .claude/skills/changelog-generator/scripts/generate_changelog.py main

这样 Codex 在收到相关请求时，可以从 AGENTS.md 中读到技能入口，然后运行脚本。

这里有一个重要的设计原则：指令只描述“目标”和“执行命令”，不描述“必须用 Codex 的某个内部功能”。这样即使后续切换 Agent 工具，技能本身也不需要重写。

4.3 通过 CLI 一次性会话运行技能

Codex 支持通过命令行启动一次性任务。可以在非交互模式中直接让 Codex 读取 AGENTS.md 并执行技能。

示例：

codex exec "生成当前分支的 CHANGELOG.md，使用 changelog-generator 技能，并把结果保存到 CHANGELOG.md"

如果当前 Codex 版本支持交互模式，也可以直接运行：

codex

然后在对话中写出同样需求。

运行后 Codex 会读取项目上下文，找到 AGENTS.md 中关于技能的说明，再运行脚本，并把 stdout 内容整理成最终输出。

4.4 验证 Codex 执行结果

技能跑完后，不能只看终端输出，还要确认实际效果。

检查点包括：

• 脚本退出码是否为 0。
• CHANGELOG.md 是否生成。
• 内容是否包含当前分支相对 main 的提交。
• 提交分组是否符合 SKILL.md 中定义的规则。
• 是否出现重复内容或误覆盖已有文件。

可以用命令快速确认：

git status --short cat CHANGELOG.md

如果 CHANGELOG.md 没有任何内容，可能是脚本运行时没有拿到提交记录。这时先手动运行脚本，排除脚本本身的问题，再检查 Agent 是否正确执行了命令。

5. 常见错误排查：安装、路径与执行器问题

Agent Skills 的报错往往不在技能本身，而在工具链。下面几类问题是社区里最常见的，排查时可以按顺序处理。

5.1 unable to locate the codex CLI binary：路径问题

错误现象：

Unable to locate the codex CLI binary. Set codex CLI path or ensure the executable is in your PATH.

这个错误说明某个程序需要调用 codex，但找不到可执行文件。

检查步骤：

which codex echo $PATH ls -l $(which codex)

如果which codex没有输出，说明 codex 不在 PATH 中。先手动安装或重新安装。

如果which codex有输出但插件仍然报错，可能是 IDE 启动时的环境变量和终端不一致。处理方式：

export CODEX_CLI_PATH="$(which codex)"

或者在 IDE 设置中手动指定 codex 可执行文件路径。

注意：修改环境变量后，必须重启终端和 IDE，而不是只打开一个新的终端标签页。

5.2 The agent execution provider did not respond in time：执行超时

错误现象：

The agent execution provider did not respond in time. This may indicate the agent took too long to complete.

这个错误通常出现在 Agent 执行脚本或等待外部响应超时的时候。

常见原因：

1. 脚本在等待用户输入，命令一直挂起。
2. 脚本执行时间太长，超过执行器限制。
3. 外部 API 或网络请求没有设置超时。
4. 任务拆得过大，Agent 在一次执行里做了太多事。

排查第一步是手动运行脚本，看是否卡住。例如：

time python .claude/skills/changelog-generator/scripts/generate_changelog.py main

如果脚本本身执行很快，问题可能在 Agent 对任务的规划上。可以尝试把任务拆小，让 Agent 先读取提交记录，再生成文件，最后单独验证内容。

5.3 model not recognized：模型名不匹配

错误现象示例：

"deepseek-v4-pro" is not a model this version of claude code recognizes

这是配置中的模型名没有被当前版本的 Claude Code 识别。

可能原因：

• 环境变量里指定了错误的模型名。
• 使用了某个上游供应商的模型名，但没有同步到 Claude Code 的模型列表中。
• Claude Code 版本较旧，不认识新模型名。

检查方式：

env | grep -i claude env | grep -i anthropic

重点检查ANTHROPIC_MODEL、CLAUDE_CODE_MODEL等变量。如果设置了不确定的模型名，先取消它，恢复默认模型再试。

注意：模型名是跟随工具版本和提供方能力变化的，不要把一个网络教程里的模型名直接复制到生产配置里。落地前先确认当前工具版本支持哪些模型。

5.4 技能不生效时的通用排查顺序

如果技能文件位于正确位置、脚本也能手动执行，但 Agent 就是不调用技能，按下面的顺序检查：

1. 技能目录是否在正确路径。项目级一般在.claude/skills/下，用户级则在用户技能目录。
2. SKILL.md 文件名是否正确，大小写是否敏感。
3. frontmatter 是否包含 name 和 description。
4. description 中是否包含足够具体的触发词。
5. 对话中是否明确提到了技能描述里的场景。
6. 技能脚本是否具有可执行权限，解释器是否存在。
7. 工具版本是否过旧，是否支持当前技能格式。
8. 是否同时存在多个同名技能，导致 Agent 选择冲突。

排查时建议先在对话中直接说“请使用 xxx 技能”，而不是等待 Agent 自己猜测。如果显式指定后仍不生效，问题大概率在技能文件本身，而不是触发匹配。

6. 设计可复用、可扩展的 Agent 技能体系

技能如果只是散落在各个项目里，时间一长会变成新的“文档债务”。真正有用的是一套能持续维护的技能体系。

6.1 三类技能：通用技能、项目技能、临时指令

不是所有能力都适合做成技能。按照复用频率和维护成本，可以把任务分成三类：

判断标准很简单：如果同样的任务下个月还会出现，才值得做成技能；如果只是一次性调研或探索，不要过早抽象。

6.2 技能命名、版本、依赖与文档规范

技能命名建议使用“动作 + 对象”的结构，例如：

• changelog-generator
• code-review-runner
• dependency-auditor
• api-doc-builder

命名要小写，使用连字符，避免特殊字符。

版本管理可以从两个层面做：

1. 在技能目录中放一个VERSION文件或README.md中记录版本。
2. 把技能库整体纳入 Git，用 commit 或 tag 管理变更。

依赖信息必须写在 SKILL.md 中，包括运行脚本所需的解释器、外部命令和系统要求。否则换一台机器后，技能可能静默失败。

一个技能库的推荐结构：

skills/ changelog-generator/ SKILL.md scripts/ tests/ README.md VERSION code-review-runner/ SKILL.md scripts/ tests/ README.md VERSION

每个技能都带 tests 和 README，可以让其他协作者快速理解技能用途，也能在 CI 中自动验证脚本没有跑挂。

6.3 从技能库到多人协作：目录与审核

多人协作时，技能库应该像代码库一样管理。

推荐做法：

1. 建立一个中央技能库仓库。
2. 每个技能一个目录，通过 PR 提交新增或修改。
3. 新增技能必须包含 SKILL.md、脚本、测试示例和 README。
4. 评审时重点检查：命令是否可执行、是否硬编码密钥、是否可能破坏环境、是否跨工具可用。
5. 团队成员把技能库 clone 到本地，再通过 symlink 或脚本将技能目录同步到技能目录。

不要直接让每个人在本地随意新建技能。没有审查的技能可能包含危险命令，尤其在 Agent 自动执行脚本的环境里，风险会被放大。

6.4 哪些任务值得做成 Skill

适合做成技能的任务通常具备以下特征：

• 流程稳定，重复出现。
• 输入输出可定义。
• 结果可以被验证。
• 可以通过脚本或命令自动完成大部分工作。

典型适合场景：

• 根据提交信息生成 changelog。
• 对变更代码执行静态检查。
• 扫描依赖版本并输出安全报告。
• 根据接口定义生成文档。
• 按团队规范生成代码骨架。

不适合做成技能的场景：

• 高度依赖实时决策。
• 需要大量人工审美和判断。
• 任务本身只出现一次。
• 无法用明确标准判断成功失败。

建议每新增一个技能前，先问一个问题：如果三个月后这个任务不再出现，我还会为它写技能吗？如果答案是否定的，就不要做。

7. 最佳实践与下一步

技能体系能跑起来只是第一步，能长期稳定运行才是目标。最后一部分整理工程实践、学习路径和学习环境与生产环境的关键差异。

7.1 编写 Agent Skill 的工程建议

以下建议来自实际项目中使用 CLI Agent 的经验，可以直接用到技能开发中。

• 不要在高频技能脚本里硬编码密钥或访问令牌。密钥通过环境变量注入，技能库提交时排除.env。
• 技能脚本默认只输出 stdout，不要擅自修改文件。这样 Agent 可以先检查结果，再由用户确认是否落盘。
• 每个技能都要在 SKILL.md 中写明“预期输出”和“验证方式”。没有验证方式的技能很难排查问题。
• 脚本执行要设置超时，避免 Agent 长时间挂起。内部脚本遇到外部请求时显式设置 timeout。
• SKILL.md 中的指令不要绑定具体 Agent 的私有能力。只描述目标和可执行命令，保留跨工具迁移能力。
• 为每个技能准备一个最小测试用例。脚本错误最好在本地直接发现，不要等 Agent 执行时才发现。
• 技能库纳入版本控制，变更走代码评审，避免出现不可追溯的“万能脚本”。

7.2 从会用 AI 到会开发 Agent 的练习路径

建议按下面的顺序练习，而不是一开始就写一个庞大的技能库。

1. 先用 Claude Code 在现有项目里完成一个小任务，观察它如何读取文件、调用命令、修正错误。
2. 写一个最小 SKILL.md，让 Agent 根据 Git 提交输出 changelog。
3. 把同一个技能迁移到 Codex，通过 AGENTS.md 或 CLI 验证执行。
4. 把两三个技能放入独立技能库，给每个技能补充测试用例。
5. 选择团队中重复出现的工作流，抽象成技能，发布评审后使用。

完成第 4 步，基本就形成了“遇到任务 -> 选择技能 -> 执行脚本 -> 人工检查”的稳定工作流。这个工作流的价值在于，即使换了新的 Agent 工具，技能资产仍然可以继续使用。

7.3 学习环境与生产环境要分开验证

学习环境可以随便创建技能、随意调整脚本，但生产环境必须有一套更严格的标准。

学习环境：

• 使用个人项目，权限范围小。
• 技能脚本可以快速迭代。
• 不存在敏感数据共享问题。

生产环境：

• 技能脚本执行前要评估对文件系统的影响。
• Agent 生成的代码必须经过 review。
• 密钥通过环境变量或密钥管理服务注入。
• 技能脚本要有日志，方便定位失败原因。
• 版本变更要有回滚方案，避免新技能把原有工作流破坏。
• 技能库只允许通过审查的 PR 合入，禁止个人直接推送脚本。

注意：Agent 自动执行脚本的能力越强，越要约束技能脚本的行为。不要写一个“删除全部未跟踪文件”的技能，除非你明确知道它会作用于哪个目录。

如果能把“技能定义”和“具体执行”分离，再配合版本管理和环境隔离，Agent Skills 就会成为一种长期有效的能力资产。下一步最有价值的练习不是收藏更多技能，而是把自己最常做的三件事固化成技能，并让它们在 Claude Code 和 Codex 上都能跑通。