企业官网建设流程全解析

从会说会写到会开发：Agent Skills 入门到实战，用 Claude Code 和 Codex 打造可复用的智能体技能

最近不少同学在群里聊同一个感受：用 AI 写代码、写文档已经很顺手了，但 AI 帮我们做的事始终限制在“对话”里。你问一句它答一句，换个项目、换个环境，同样的问题可能要重新调半天提示词，之前积累的经验根本带不走。

这就是 Agent 和普通 AI 助手的核心区别。普通 AI 是“你问它答”，Agent 是“你交代目标，它自己拆解、执行、交付”。而 Agent 能否真正稳定地干活，关键又取决于它有没有一套可复用的“技能体系”。

我从 Claude Code 和 Codex 的实际使用出发，梳理了一套从零搭建 Agent Skills 的方法。本文包含完整的环境配置、技能目录结构、SKILL.md 编写规范、可运行的示例和常见报错排查方案，适合刚从对话式 AI 转向 Agent 开发的同学参考。读完你可以自己定义一个项目级或团队级技能包，让 Agent 在后续任务中持续复用。

1. 背景与核心概念

1.1 从“会用 AI”到“会开发 Agent”

先打个比方。

你让一个实习生干活，如果只说“帮我做个数据报表”，他大概率会反问一堆问题：数据在哪？报表要给谁看？用什么格式？但如果这个实习生已经带过很多次，他自己就知道该查哪些表、按什么口径统计、邮件发给谁。

Agent 也是这个道理。大模型本身是“应届生”，知识面广，但做事没有固定章法。而 Agent Skills 就是给这个“应届生”的一份标准化工作手册，里面写着：这个任务应该按什么流程做、有哪些注意事项、遇到什么情况调用哪个脚本、结果输出成什么格式。

所以可以这样理解：

• Prompt（提示词）是一次性的口头交代。
• Skill（技能）是沉淀下来的标准作业流程，可以被反复调用。
• Agent（智能体）是具备一组 Skill、能自主规划执行路径的执行者。

1.2 什么是 Agent Skills

Agent Skills 不是某个厂商的独家概念，而是一种让大模型 Agent 具备“特定领域操作能力”的封装方式。它通常包含一个描述技能用途和调用方式的说明文件，以及配套的脚本、模板、数据或配置。

以 Claude Code 为例，Skills 是放在特定目录下的能力模块。Agent 在执行任务时，如果发现当前任务匹配某个 Skill 的描述，就会自动加载这个 Skill 的说明，并按照里面的步骤和脚本来操作。

Codex 同样支持类似机制。在实际开发中，我们可以把常用的代码审查、接口测试、日志分析、环境部署等操作封装成 Skill，让 Agent 在接到任务时“自动想起”这些经验。

1.3 Agent Skills 解决什么问题

我总结了一下，Agent Skills 主要解决四类问题：

更重要的是，Skill 让 Agent 从“泛泛的通用助手”变成“懂你业务的专业助手”。同一个 Agent，加载了“支付接口测试”的 Skill，它处理支付项目时就会自动带上这套经验；加载了“日志排查”的 Skill，它遇到线上报错就知道该怎么定位。

2. 环境准备与版本说明

2.1 本文使用的工具链

为了把概念讲清楚，本文以 Claude Code 和 Codex CLI 两个工具为例。

• Claude Code：Anthropic 推出的终端编程助手，支持在项目目录中读取文件、执行命令、修改代码。
• Codex CLI：OpenAI 推出的命令行编码智能体，通过自然语言驱动在本地仓库中完成任务。

两者的核心思路一致：通过 CLI 把大模型连接到你的项目环境，Agent 在沙箱或授权模式下执行操作。

2.2 Claude Code 安装

Claude Code 通常通过 npm 安装。在确认本机已安装 Node.js 18+ 的前提下，执行：

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

安装完成后，在项目目录下运行：

claude

首次运行会引导你完成登录认证。需要说明的是，不同版本的登录方式和 API 配置有一定差异，如果网络环境中特殊变量较多，可能需要配置代理参数，具体以官方安装文档为准。

2.3 Codex CLI 安装

Codex CLI 同样可以通过 npm 安装：

npm install -g @openai/codex

安装后执行：

codex

如果之前安装过旧版本，建议先升级：

npm update -g @openai/codex

某些 IDE 插件会内置 Codex CLI，但插件内配置的 CLI 路径可能与全局安装路径不一致，容易触发“找不到 codex cli binary”的报错，这在第 5 章会专门说明。

2.4 版本说明

本文写作时，Claude Code 和 Codex CLI 的版本更新速度都非常快。不同版本对 Skills 目录的支持位置、配置字段可能有细微差异。

如果你的版本行为与本文描述不一致，请优先查阅官方 CHANGELOG。以下示例重点演示“思路与规范”，不依赖某个精确版本，代码中的目录结构和核心概念在目前的主流版本中都是适用的。

建议在开始之前统一确认版本：

claude --version codex --version npm -v node -v

3. Agent Skills 核心机制拆解

3.1 SKILL.md 是技能的灵魂

无论 Claude Code 还是 Codex，Agent Skills 的核心都是一个 Markdown 文件，通常命名为SKILL.md。

这个文件的作用，是告诉 Agent 三件事：

1. 这个技能是干什么的—— 技能的用途描述，用于 Agent 判断是否调用。
2. 这个技能怎么做—— 详细的步骤、规则、注意事项。
3. 这个技能能调用什么资源—— 相关的脚本、模板、二进制文件放在哪里。

可以这样理解：SKILL.md就是 Agent 的“任务说明书”，Agent 在执行前先读说明书，再动手。

3.2 技能目录的标准结构

一个典型的 Skill 目录如下：

skills/ code-review/ SKILL.md rules/ security-rules.md scripts/ run_review.sh templates/ review_report.md

各目录的作用：

• SKILL.md：核心说明文件，Agent 首先读取它。
• rules/：存放补充规则，比如安全红线、命名规范。
• scripts/：存放可执行脚本，Agent 可以调用这些脚本完成操作。
• templates/：存放输出模板，保证生成结果格式统一。

当 Agent 配置了skills目录后，在对话中遇到匹配任务，会自动读取对应 Skill 的SKILL.md，按照说明执行。

3.3 SKILL.md 的内容结构

参考当前社区通用的 Skill 编写规范，一份完整的SKILL.md应该包含以下区块：

下面先看一个最小示例：

--- name: python-unit-test description: 当用户要求为 Python 项目编写或补充单元测试时使用。 --- # Python 单元测试技能 ## 适用场景 - 新建测试文件 - 为现有函数补充测试用例 - 运行测试并检查覆盖率 ## 执行步骤 1. 确认项目使用的测试框架（pytest / unittest） 2. 根据被测模块创建对应的 test_ 文件 3. 编写测试用例，覆盖正常输入、边界输入、异常输入 4. 在项目根目录执行 pytest -v，确认全部通过 ## 输出要求 - 测试文件命名规范：test_<模块名>.py - 测试函数命名规范：test_<被测函数>_<场景>

这个文件并没有调用任何脚本，但它已经算是一个完整的 Skill。因为它定义了一套标准作业流程，Agent 在遇到“写单测”的任务时，会按照这个流程执行，而不是凭大模型的“临场发挥”。

3.4 Agent 如何决定调用哪个 Skill

当 Agent 加载了 Skills 配置后，每一步决策过程大致如下：

1. 读取用户输入的任务。
2. 扫描所有已注册 Skill 的description字段。
3. 计算任务与 Skill 描述的匹配度。
4. 如果匹配，读取该 Skill 的详细步骤，按步骤执行。
5. 如果多个 Skill 都匹配，Agent 会规划组合方案。

因此，description写得好不好，直接决定技能能不能被正确触发。它应该尽量包含“触发关键词”和“适用场景”，而不是写得模棱两可。

4. 完整实战：从零创建并调用一个 Agent Skill

这一节我们做一个带脚本、带模板、可运行的完整案例。目标：开发一个“Git 仓库健康检查”技能，Agent 通过这个技能自动分析仓库状态、识别常见风险，并输出一份结构化报告。

4.1 创建项目结构

先创建技能目录：

mkdir -p skills/git-health-check/{scripts,templates}

最终目录结构为：

skills/git-health-check/ SKILL.md scripts/ check_repo.sh templates/ health_report.md

4.2 编写 SKILL.md

在skills/git-health-check/SKILL.md中写入：

--- name: git-health-check description: 当用户要求检查 Git 仓库状态、分析分支健康状况、识别大文件或长期未合并分支时使用。典型触发词包括 git 检查、仓库健康、分支清理、大文件排查。 --- # Git 仓库健康检查技能 ## 适用场景 - 定期检查仓库状态 - 部署前确认仓库干净 - 识别长期未合并的分支 - 排查仓库体积过大问题 ## 执行步骤 ### 1. 执行仓库状态检查 运行 `scripts/check_repo.sh`，传入仓库路径参数： ```bash bash scripts/check_repo.sh /path/to/repo

2. 解析脚本输出

脚本会输出以下信息：

• 当前分支和最近提交
• 未合并分支列表
• 超过 10MB 的大对象（如存在）
• 仓库总大小

3. 根据结果生成报告

使用templates/health_report.md作为模板，将上一步的结果填入报告。

输出要求

• 报告必须包含“风险等级”字段：
  • 高：存在大于 50MB 的游离大文件
  • 中：存在超过 30 天未合并的分支
  • 低：以上条件均不满足
• 每个风险项必须给出建议操作

注意事项

• 只做只读检查，不执行 git clean、git branch -D 等破坏性命令。
• 如果仓库路径不存在或不是 Git 仓库，立即停止并报告错误。

### 4.3 编写检查脚本 在 `scripts/check_repo.sh` 中写入： ```bash #!/bin/bash # 文件路径：skills/git-health-check/scripts/check_repo.sh # 功能：只读检查 Git 仓库健康状况 REPO_PATH="$1" if [ -z "$REPO_PATH" ]; then echo "错误：请传入仓库路径" exit 1 fi if [ ! -d "$REPO_PATH/.git" ]; then echo "错误：$REPO_PATH 不是有效的 Git 仓库" exit 1 fi cd "$REPO_PATH" || exit 1 echo "===== 当前分支与最近提交 =====" git branch --show-current git log -1 --oneline echo "" echo "===== 未合并分支列表 =====" git branch --no-merged HEAD | head -20 echo "" echo "===== 仓库总大小 =====" du -sh .git 2>/dev/null | cut -f1 echo "" echo "===== 大文件检查（超过 50MB 的 Git 对象） =====" git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ { if ($3 > 50000000) print $4, $3 }' | sort -k2 -n -r | head -10 echo "" echo "检查完成"

给脚本添加执行权限：

chmod +x skills/git-health-check/scripts/check_repo.sh

这个脚本做的事情很清晰：

• 先用git branch --no-merged HEAD找到未合并分支，这是最常见的仓库维护盲点。
• 再用du -sh .git判断仓库体积。
• 最后通过git rev-list --objects --all配合cat-file --batch-check扫描历史中的大文件对象。

整套操作都是只读的，不会改动仓库任何状态，符合安全边界要求。

4.4 编写报告模板

在templates/health_report.md中写入：

# Git 仓库健康检查报告 - 检查时间：`{{date}}` - 仓库路径：`{{repo_path}}` ## 风险等级 {{risk_level}} ## 仓库状态 - 当前分支：{{current_branch}} - 最近提交：{{latest_commit}} - 仓库大小：{{repo_size}} ## 未合并分支 {{unmerged_branches}} ## 大文件风险 {{large_files}} ## 建议操作 {{recommendations}}

这个模板的意义在于：它定义了输出的固定格式。Agent 每次生成报告时，都会按照同样的结构输出，不会出现“这次用表格、下次用列表”的混乱情况。

4.5 配置 Agent 使用技能

以 Claude Code 为例，你可以在项目配置文件或启动参数中指定 Skills 目录。

在项目根目录创建.claude/settings.json（不同版本路径可能不同）：

{ "skills": { "paths": [ "./skills" ] } }

然后在项目目录启动 Claude Code：

claude

在对话中输入：

帮我检查当前仓库的健康状态，输出一份报告

Agent 会读取skills/git-health-check/SKILL.md，识别出任务匹配，执行脚本并生成报告。

如果使用 Codex，可以在启动时通过指令或项目配置文件指定 skills 位置。具体字段名随 CLI 版本会有变化，建议用codex --help查看当前版本支持的配置方式。

4.6 运行与验证

假设仓库路径是/home/user/demo-repo，手动验证脚本：

bash skills/git-health-check/scripts/check_repo.sh /home/user/demo-repo

预期输出片段：

===== 当前分支与最近提交 ===== main a1b2c3d fix: update readme ===== 未合并分支列表 ===== feature/login feature/payment ===== 仓库总大小 ==== 8.2M ===== 大文件检查（超过 50MB 的 Git 对象） ==== 检查完成

如果输出中没有大文件记录，说明仓库状态健康。如果出现了大文件，则需要进一步定位和处理。

通过这个案例可以看到，一个完整的 Skill 涉及三部分工作：写说明（SKILL.md）、写逻辑（脚本）、定格式（模板）。三者缺一不可。

5. 常见问题与排查思路

在实际配置和使用 Agent Skills 的过程中，我整理了几个高频报错场景，尤其是 Claude Code 和 Codex 混用时，环境问题非常典型。

5.1 codex cli binary 找不到怎么办

这个问题多发生在 VSCode 等 IDE 插件场景。原因通常是插件默认去找某个固定路径下的codex，而你的实际安装路径不在其中。

排查步骤：

# 1. 确认 codex 是否安装 codex --version # 2. 查看 codex 实际安装位置 which codex # 3. 在 IDE 插件设置中手动指定该路径

如果你使用 npm 全局安装，在 Linux/macOS 上路径通常在/usr/local/bin/codex或$(npm prefix -g)/bin/codex。

5.2 模型名不被识别怎么办

deepseek-v4-pro is not a model this version of claude code recognizes这类报错的本质，是配置文件中写了一个当前版本不认识的模型标识。

这个问题在两种情况下常见：

• 你手动改了模型配置，写错了模型名称。
• 当前 Claude Code 版本较旧，还不支持这个新模型。

处理方式：

# 升级 Claude Code npm update -g @anthropic-ai/claude-code

然后检查项目或用户级配置文件，把模型名改成官方文档支持的标识。如果你确实需要接入其他模型的 API，一定要确认当前版本对自定义 model 的支持方式和字段规则。

5.3 Shell 脚本报错排查

如果 Skill 引用了 Shell 脚本，但 Agent 运行时报错，建议先手动执行脚本，确认脚本本身逻辑没有问题。

关注几个点：

• 脚本首行是否写了#!/bin/bash。
• 是否给脚本加了执行权限。
• 脚本中是否有 Linux 和 macOS 不兼容的命令。
• 路径是否包含空格，导致参数解析错误。

把这些检查项写进SKILL.md的注意事项，可以有效减少后续 Agent 调用失败的概率。

6. 最佳实践与工程建议

6.1 Skill 的粒度要适中

这可能是设计 Skills 时最容易纠结的问题。

Skill 太大会变得臃肿，Agent 加载后反而不容易快速定位关键信息。Skill 太小又会产生大量碎片目录，维护成本上升。

我的建议是：一个 Skill 只解决一个内聚的业务问题。

比如：

• “代码审查”是一个 Skill，不要把它拆成“审查 Python”“审查 Java”“审查 Go”三个 Skill。
• 但“支付接口测试”和“用户登录测试”应该拆开，因为它们的依赖环境、测试重点完全不同。

判断粒度是否合适的标准很简单：如果 Agent 在执行某个任务时只需要读一个 SKILL.md 就能完成，粒度就是对的。

6.2 SKILL.md 的 description 要适配触发机制

Agent 是通过扫描 description 来决定是否加载技能的。所以 description 的写法直接影响触发成功率。

好的写法：

description: 当用户要求对 Python 项目执行代码审查、检查潜在 bug、评估代码风格时使用。触发器包括 python review、code review、代码检查。

差的写法：

description: 代码审查相关工具。

关键词覆盖越具体，Agent 越容易做出正确判断。但也不要为了堆关键词而写出一段不通顺的话，保持自然语言，同时让关键触发词出现在前后文即可。

6.3 脚本必须做防御性校验

Skill 中的脚本会被 Agent 自动调用，这意味着脚本必须比普通脚本更稳健。因为你无法预判 Agent 会在什么环境下、传入什么参数去运行它。

核心防御点：

• 参数为空时，输出清晰错误并退出。
• 路径不存在时，给出提示，不要继续执行。
• 禁止在脚本中写死绝对路径，除非你有充分理由。
• 破坏性操作（删除、覆盖、远程变更）默认禁止，如确有必要，必须加二次确认参数。

以本文的check_repo.sh为例，第一步就校验参数和仓库路径，这不仅仅是“严谨”，更是避免 Agent 在错误路径上越走越远。

6.4 输出模板化

Agent 执行 Skill 的最终产物，最好通过模板来约束格式。原因有两点：

• 稳定格式方便后续自动化处理。
• 模板能提醒 Agent 不遗漏关键字段。

在实际项目中，模板可以结合 Markdown、JSON、CSV 等格式。如果 Skill 的产出要交给下游程序，建议使用 JSON 模板并附上字段说明。

6.5 用 Git 管理 Skill 仓库

Agent Skills 本质上是文本文件，非常适合用 Git 管理。

建议的团队协作模式：

skills-repo/ skills/ code-review/ git-health-check/ docs/ CONTRIBUTING.md

团队成员通过 Pull Request 更新技能，评审者重点确认三件事：

1. SKILL.md 的 description 是否清晰。
2. 脚本是否有明显的安全和兼容性问题。
3. 输出模板是否与团队规范一致。

这样，Skills 就从“个人经验”变成了“团队知识资产”。

6.6 权限与安全边界

Agent 的能力随着 Skills 扩展会越来越强，这也意味着风险面在扩大。必须明确以下安全边界：

• 技能脚本默认只读，需要写操作时单独授权。
• 涉及生产环境、外部服务、支付接口的技能，必须经过严格评审。
• 技能中不要硬编码任何密钥、Token、密码。
• 敏感操作技能建议增加人工确认环节。

在 Claude Code 和 Codex 的使用中，也要了解各自的权限体系和沙箱机制。优先以最小权限运行 Agent，不要图省事直接给 root 或管理员权限。

7. 总结与下一步实战建议

Agent Skills 是连接大模型和真实工程世界的一座桥。没有 Skills 的 Agent 像一个空有热情但没有工作方法的新人；有了 Skills，它才能真正融入团队节奏，按标准流程产出稳定结果。

本文从概念、环境、机制、实战到排错，完整走了一遍：

• 理解了 Agent Skills 是什么，以及它如何解决经验沉淀问题。
• 掌握了 SKILL.md 的编写结构和核心原则。
• 动手实现了一个 Git 仓库健康检查技能，包含脚本、模板、调用配置。
• 梳理了 Claude Code 与 Codex 使用中的高频报错和处理方式。
• 总结了 Skill 粒度控制、输出模板、安全边界等工程建议。

下一步，建议你做三件事：

1. 复盘自己的高频操作：回顾最近一个月你让 AI 重复做的事情，挑出频率最高的 3 个任务。
2. 把其中一个任务封装成 Skill：不需要一开始就写脚本，先用 SKILL.md 固化流程，跑通了再加脚本和模板。
3. 在真实项目中迭代：把 Skill 放入正式项目，观察 Agent 的调用效果，根据失败案例调整 description 和步骤。

Agent 开发的学习路线，本质上就是“把你会做的事情，一步步移交给 Agent”。Skills 就是你移交经验的载体。从现在开始，把第一篇 SKILL.md 写下来吧。