从提示词到Agent Skills：用Claude Code与Codex构建可复用技能包

过去一两年里不少开发者都有过这样一种经历明明花了很多时间研究提示词把各种“角色设定”“任务拆解”背得滚瓜烂熟但换一个项目、换一个仓库一切又得重来。对话里反复粘贴同样的背景说明让 AI 按同样的规范生成代码结果换个会话AI 又“失忆”了。问题不在模型而在使用方式。你还在“用 AI”没有“开发 Agent”。这两者的分界线就是 Agent Skills。基于 Claude Code 和 Codex 这类终端编程智能体把个人和团队的最佳实践沉淀成可复用的“技能包”你会发现 AI 写代码这件事从“碰运气”变成了“流水线”。这篇文章就从概念讲起结合 Claude Code 与 Codex 的实际用法带你完整走一遍“从会用 AI 到会开发 Agent”的路径。1. 这篇文章真正要解决的问题先说一个判断Agent Skills 并不是什么高深莫测的神经网络技术它本质上是一种“工程化组织 Agent 能力”的方式。你没有必要先精通机器学习再谈 Agent 开发恰恰相反你只需要理解文件、目录、脚本和约定就能为 AI 智能体编写技能。那为什么还要专门写一篇文章因为大多数开发者在实践时会卡在三个地方。第一不知道 Agent 和聊天机器人有什么区别。很多人用 ChatGPT、Claude 网页版写提示词写得很好但一旦要进入命令行环境面对一个能自主读代码、改文件的 Agent就不知道如何约束它、引导它。第二不知道技能Skill到底应该长什么样。是写一段更长的提示词还是写一个脚本还是搞一个插件不同工具说法不一概念混乱。第三不知道如何让多个工具共用同一套技能。团队里有人用 Claude Code有人用 Codex如果每个工具学一套技能体系维护成本很高。这篇文章会依次解决这三个问题。你想不想跑通一个最小可用的 Skill想。想不想在 Claude Code 和 Codex 里都能调用同一套技能想。那这篇文章就是合适的切入点。读过之后你至少能获得三样东西一套关于 Agent Skills 的基本心智模型一个可以直接复制使用的技能包模板一份覆盖安装、调用、排错和工程化落地的完整操作清单。2. Agent、Agent Skills 与相关概念2.1 什么是 Agent先给 Agent 下一个清晰的定义一个能够在目标驱动下自主规划步骤、调用工具、读取环境信息并在最小监督下完成任务的智能体系统。它和普通聊天助手最大的区别是“行动性”。普通聊天只产生文本Agent 会执行命令、读写文件、运行测试、修改代码。它不是“给你建议怎么做”而是“真的去做”。编程场景里常见的 Agent 形态包括Claude Code在终端里运行的编程 AgentCodexOpenAI 提供的命令行编程 AgentCursor 里的 Agent 模式在 IDE 中自主完成多文件修改。这些工具的共同特点是都运行在本地开发环境里能访问当前项目目录能执行终端命令能调用大模型完成推理和代码生成。2.2 什么是 Agent SkillsAgent Skills 可以理解为为了完成某一类特定任务预先定义好的“指令 脚本 参考资料”的组合包。它在不同工具里有不同的落地形式但核心思想一致。以 Claude Code 的 Skills 为例一个技能通常就是一个目录目录里有一个SKILL.md文件作为入口文件里写清楚这个技能是干什么的、怎么用、有什么约束旁边可以放脚本和模板。如果把 Agent 比作一名新入职的工程师那 Skills 就是给他准备的“部门工作手册”。手册里写明遇到什么场景用哪个脚本代码要符合什么规范测试怎么跑发布前要检查什么。没有手册这位工程师可能很聪明但行为不可控有手册他的产出稳定、可预期、可复制。2.3 Skills 与 Prompt、Tool、MCP 的区别这是新手最容易混淆的地方。我们用一张表说明。概念本质解决的问题例子Prompt一段对话指令引导模型本次回答方向“请用 Python 写一个快速排序”Tool一个可被调用的函数/命令让 Agent 能执行外部动作文件读接口、终端执行接口MCP一种工具接入协议统一工具调用的数据传输方式让 Agent 接入数据库、GitHubSkill指令与资源的组合包让 Agent 具备“会做某类任务”的能力“创建 Python 项目脚手架”技能Agent完整自主执行系统在目标驱动下完成任务Claude Code 本身可以看到Prompt 是一次性的Skill 是可复用的Tool 是能力的原子单位Skill 是能力的组合单位MCP 是工具接入的“插座标准”Skill 则是“插上去之后怎么用”的使用说明。一句话总结Skill 站在比 Prompt 更高的抽象层次上它把“你怎么跟 AI 说”升级为“这个 AI 会什么”。2.4 Skills 的工作机制在 Claude Code 中一个 Skill 目录的典型结构是my-skill/ ├── SKILL.md # 技能说明Agent 最先读取的文件 ├── scripts/ # 可执行脚本或代码文件 ├── templates/ # 模板文件用于生成新内容 └── references/ # 参考资料作为技能的知识库SKILL.md通常会包含 YAML 格式的 Front Matter 和正文指令。--- name: create-python-project description: 创建一个规范的 Python 项目脚手架包含目录结构、依赖管理配置、README 和基础测试框架。 --- # 技能说明 当用户要求创建 Python 项目脚手架时使用本技能。 ## 执行步骤 1. 检查目标目录是否已存在。 2. 按照 templates/ 下的目录结构生成项目。 3. 初始化 Git 仓库。 4. 创建虚拟环境并安装基础依赖。 5. 运行测试验证脚手架可用。当 Agent 接到相关任务时会先读取SKILL.md理解任务步骤然后调用脚本、读取模板、完成生成任务。整个过程对用户来说是半自动化的你只需要说“用 create-python-project 技能创建一个新项目”Agent 就会按照手册去执行。3. 为什么选择 Claude Code 与 Codex 作为实践载体3.1 Claude Code 的特点Claude Code 是 Anthropic 推出的终端编程智能体是目前对 Agent Skills 支持最直观、最文件化的工具之一。它直接在项目目录里运行能够读取上下文、调用终端命令、按步骤完成代码修改。它的优势在于长上下文能力强适合处理大型代码库原生支持 Skills 目录技能可以放在全局配置或项目目录中交互模式清晰既能全自主执行也能一步步确认。3.2 Codex 的特点Codex 是 OpenAI 推出的命令行编程 Agent定位同样是“在终端里帮你写代码”。与 GitHub 工作流、OpenAI 模型生态的集成是它的优势。很多开发者最初接触 Codex 时会遇到“Codex CLI 路径找不到”的问题这是因为 Codex 在部分 IDE 插件或图形化工具中需要通过环境变量指定可执行文件路径。这恰好也说明了编程 Agent 类工具在工程化落地时环境配置是绕不开的第一步。3.3 两者如何配合Claude Code 和 Codex 并不是二选一的关系。在实际工作流中可以按任务类型选工具也可以用同一套技能包分别驱动两个工具。关键在于不要让你的技能体系绑定某个特定工具。尽量把技能定义为“目录 文件 脚本”的通用形式再为不同工具编写薄薄的适配层。这样团队里有人用 Claude Code有人用 Codex技能包仍然可以共用。4. 环境准备与基础配置开始创建 Skills 之前先准备环境。步骤不算复杂但值得逐一确认因为不少人在这一环就卡住了。4.1 前置条件Node.js 环境建议使用较新的稳定版本Git用于仓库管理和技能版本管理API Key用于调用对应的模型服务一个测试用项目目录建议新建一个空目录避免影响已有工程。4.2 安装 Claude CodeClaude Code 的安装方式以官方文档为准。通常可以通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后执行版本检查claude --version如果能够正常输出版本号说明安装成功。接下来在项目目录内启动cd ~/work/learn-agent claude首次启动时CLI 会引导你完成登录和授权。这个过程需要你有可用的 Anthropic 账号和 API Key。如果公司或团队有自己的网关也需要在这一步配置好访问地址。这里真正容易踩坑的地方在于不要在公司内网环境里跳过代理配置直接启动。很多人的报错不是模型问题而是网络访问问题。正确的做法是先确认命令行能否正常访问模型服务的接口地址再启动 Claude Code。4.3 安装 Codex CLICodex 的安装方式同样以官方文档为准早期版本通常也走 npm 安装npm install -g openai/codex安装完成后在 IDE 或终端工具中找到 Codex 可执行文件路径确认路径正确后再在需要调用 Codex 的插件中配置该路径。which codex如果系统提示“unable to locate the codex cli binary”通常有两种原因Codex 没有安装成功或者 npm 全局 bin 目录不在 PATH 中IDE 插件配置的 CLI 路径与实际路径不一致。解决方式是先通过which codex找到真实路径再根据具体 IDE 的配置项填进去。4.4 配置模型无论是 Claude Code 还是 Codex都会涉及模型配置。Claude Code 默认使用 Anthropic 的 Claude 系列模型Codex 默认使用 OpenAI 模型。也有一些开发者通过配置把第三方模型接入这类 CLI 工具但这通常需要工具本身支持自定义模型端点属于进阶玩法不建议新手一开始就折腾。配置模型时注意三点模型名称要写准确不存在的模型名会直接报错API Key 通过环境变量或配置文件提供不要硬编码到项目里如果模型名或 Key 有变动先重启 CLI 工具再测试。5. 从零创建第一个可复用的 Agent Skill理论说完了进入实战。我们创建一个“Python 项目脚手架”技能。这个技能选得比较巧它有一定复杂度涉及目录生成、文件写入、命令执行但又不依赖外部服务非常适合作为最小示例验证完整流程。5.1 创建技能目录在统一管理目录下创建技能项目mkdir -p ~/skills/create-python-project/{scripts,templates,references}我们把所有技能放在~/skills目录下每个技能一个子目录。未来如果想和团队共享直接把这个目录变成一个 Git 仓库推送到内部代码托管平台即可。5.2 编写 SKILL.md在create-python-project目录下创建SKILL.md--- name: create-python-project description: 创建符合团队规范的 Python 项目脚手架生成目录结构、依赖管理、README、测试框架并完成虚拟环境和 Git 初始化。 --- # create-python-project 当用户要求“创建一个 Python 项目”“初始化 Python 工程”或“搭建项目脚手架”时使用本技能。 ## 输入 - 项目名称必填 - 目标目录可选默认为当前目录下的项目同名子目录 ## 执行步骤 1. 在目标目录下创建项目目录。 2. 拷贝 templates/ 中的目录结构和文件到项目目录。 3. 运行 scripts/init_project.sh传入项目名和目录路径。 4. 脚本会完成以下工作 - 创建 pyproject.toml - 创建 src 和 tests 目录 - 创建 README.md - 初始化 Git 仓库 - 创建 .venv 虚拟环境 - 安装最小依赖 - 运行一次测试 5. 最后向用户报告项目路径和后续开发建议。 ## 约束 - 不要修改模板中已经确定的版本号除非用户明确要求。 - 如果目标目录已存在文件先列出冲突不要直接覆盖。 - 初始化 Git 仓库前确认用户是否需要避免在大型仓库中重复初始化。这份SKILL.md最关键的地方是它告诉 Agent“什么时候用”“按什么步骤做”“有哪些约束”。描述部分写得好不好直接影响 Agent 能不能在正确时机主动调用这个技能。5.3 编写脚手架脚本技能目录中的scripts/init_project.sh是实际的可执行脚本#!/usr/bin/env bash # 文件路径~/skills/create-python-project/scripts/init_project.sh set -euo pipefail PROJECT_NAME${1:?project name is required} TARGET_DIR${2:-$PROJECT_NAME} if [ -e $TARGET_DIR ] [ -n $(ls -A $TARGET_DIR 2/dev/null) ]; then echo Error: target directory $TARGET_DIR is not empty. exit 1 fi mkdir -p $TARGET_DIR/src/$PROJECT_NAME $TARGET_DIR/tests cat $TARGET_DIR/pyproject.toml EOF [project] name $PROJECT_NAME version 0.1.0 requires-python 3.11 [tool.pytest.ini_options] testpaths [tests] EOF cat $TARGET_DIR/README.md EOF # $PROJECT_NAME Generated by create-python-project skill. EOF cat $TARGET_DIR/tests/test_placeholder.py EOF def test_placeholder(): assert True EOF cat $TARGET_DIR/src/$PROJECT_NAME/__init__.py EOF $PROJECT_NAME package. EOF cd $TARGET_DIR git init -q python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip -q .venv/bin/python -m pip install pytest -q .venv/bin/python -m pytest -q echo Project $PROJECT_NAME created at $TARGET_DIR给脚本加执行权限chmod x ~/skills/create-python-project/scripts/init_project.sh这个脚本虽然简单但体现了 Skill 的一个重要原则把可以脚本化的步骤尽量脚本化不要每次让模型现场发挥。模型只需要负责理解用户意图、调用脚本、解读结果大量确定性的操作交给脚本处理稳定性和可测试性都更高。5.4 模板文件的作用模板文件的价值在于沉淀团队规范。以上面的脚手架为例pyproject.toml的版本号、依赖固定方式、测试目录布局都可以在templates/里预先放好标准版本脚本直接拷贝即可避免每次生成时因模型自由度太高而产出不一致的配置。更复杂的技能比如“新服务上线检查单”或“数据库变更模板”模板的价值会更明显。你会希望每一次变更都从同一个标准起点出发而不是让模型自由发挥。6. 在 Claude Code 与 Codex 中调用 Skill6.1 在 Claude Code 中加载技能Claude Code 支持通过配置找到技能目录。你可以在项目的设置文件或全局配置中指定技能路径。具体配置项以工具当前版本为准但通用思路是把~/skills目录加入技能搜索路径。启动 Claude Codeclaude在对话中直接描述任务请使用 create-python-project 技能在 demo_project 目录创建一个 Python 项目脚手架。Agent 会根据SKILL.md的description匹配到这个技能然后读取SKILL.md正文按步骤执行。你还可以验证 Agent 是否真的识别了技能你有哪些可用的技能分别适用于什么场景如果配置正确Agent 会返回技能列表和用途说明。如果它完全没有提到你创建的技能通常说明技能路径没有配置对。6.2 在 Codex 中管理技能Codex 目前更习惯通过项目目录下的AGENTS.md文件来加载项目级指令。你可以把 Skills 的核心逻辑收敛到AGENTS.md中或者在AGENTS.md里说明技能目录的位置让 Codex 在需要时去读取技能包。一个简化的AGENTS.md示例# 项目级 Agent 指令 - 当用户要求创建 Python 项目脚手架时阅读 ~/skills/create-python-project/SKILL.md按其中步骤执行。 - 遇到通用脚本任务时优先检查 ~/skills 下是否有对应技能。这种做法保持了技能的独立性技能文件仍然放在统一目录中Codex 通过AGENTS.md索引到它们。6.3 验证运行结果无论使用哪个工具技能执行成功后你应该能观察到以下结果demo_project目录被创建目录内包含src、tests、pyproject.toml、README.md.venv虚拟环境存在测试命令执行成功终端输出测试通过信息。验证命令cd demo_project ls -la .venv/bin/python -m pytest如果这个 Skill 是真正被复用的你会在不同的项目中得到结构一致、内容可预期的新项目。这也正是技能化的价值体现不是追求单次生成的“惊艳”而是追求每次生成的“一致”。7. 常见问题与排查思路把实践中容易出现的问题整理成一张排查表。下面的内容来自大量开发者反馈和常见配置问题遇到问题时建议按表格顺序排查。问题现象可能原因排查方式解决方案claude命令找不到Node.js 版本过低或 npm 全局目录不在 PATH执行node -v、npm -v检查 npm 全局 bin 路径升级 Node.js将 npm 全局 bin 目录加入 PATHunable to locate the codex cli binaryIDE 插件配置的 CLI 路径不正确执行which codex获取真实路径将真实路径填入 IDE 配置并重启 IDEAgent 没有识别我的技能技能路径未配置或SKILL.md的 description 写得不清晰在对话中询问“你有哪些可用技能”检查技能路径配置优化 description 中的关键词模型名称报错配置了不存在的模型名或版本不匹配查看命令行提示和配置文件改为工具支持的标准模型名重新加载配置Agent 执行超时网络延迟过高或模型服务响应慢查看日志确认请求是否发出检查网络连接配置合理的代理降低单次任务复杂度脚本执行失败缺少执行权限或依赖未安装手动运行脚本观察报错执行chmod x安装缺少的依赖敏感操作没有确认技能描述中未设置确认约束检查SKILL.md的约束部分明确规定“删除文件/覆盖文件前必须用户确认”技能版本混乱技能目录没有接入版本管理检查技能目录是否在 Git 仓库中将技能统一放到 Git 仓库按语义化版本打标签补充说明网络层面如果遇到访问问题应该从正常的网络检查和合规网络配置入手不要使用不规范的访问方式。生产环境中还要注意 API Key 的密钥管理和访问审计。8. 工程化最佳实践8.1 技能粒度小而精而不是大而全一个 Skill 最好只解决一类问题。例如“创建 Python 项目脚手架”是一个合理粒度“创建前后端完整项目”就是一个过大粒度。粒度越小越容易被 Agent 在合适的时机识别和复用也越好测试。8.2 命名与描述规范name使用 kebab-case例如create-python-project、db-migration-review。description要写清楚“什么时候用”和“做什么”。因为 Agent 很多情况下是依据 description 来决定要不要调用技能的。描述里应有明确的任务关键词和适用场景写得太抽象Agent 会错过它。8.3 技能也要做版本管理技能本质上是代码资产应当纳入 Git 仓库管理。推荐目录结构skills-repo/ ├── README.md ├── create-python-project/ │ ├── SKILL.md │ ├── scripts/ │ ├── templates/ │ └── references/ └── code-review/ ├── SKILL.md ├── scripts/ └── templates/技能改动应当走 Code Review和代码改动一样有评审过程。你可以为技能仓库写一个自己的小测试脚本创建临时目录执行技能对应的脚本断言生成的文件结构是否符合预期。8.4 安全边界与最小权限这是工程化落地中最重要的一环。给 Agent 的技能脚本设置最小权限不要用管理员权限运行。技能脚本中如果涉及删除文件、修改配置、执行数据库操作一律在SKILL.md的约束部分写明必须先向用户展示将要执行的操作得到确认后才能继续。例如## 约束 - 删除或覆盖任何文件前必须列出完整文件路径并请求用户确认。 - 禁止修改 .git 目录下的内容。 - 涉及密钥和密码的读取一律提示用户手动输入不要读取环境变量中的敏感值。8.5 团队共享与知识沉淀技能库最有价值的形态是团队级知识库。当团队里有人总结出高效的工作流时把它沉淀成一个 Skill其他成员就能直接复用。落地方式在团队内部搭建技能仓库GitLab/GitHub Enterprise在 README 中写明每个技能适用场景和维护人用 issue 或 MR 流程管理技能变更定期评审技能列表删除不再使用的技能。8.6 从“会写提示词”到“会设计技能”最后要强调的是一种思维转变。提示词思维是给 AI 写一段话期待它在当下给出好结果。技能思维是给 Agent 设计一套可重复执行的流程期待它在任何时间、任何项目里都给出稳定结果。所以设计 Skill 的时候多问自己几个问题这个流程的输入是什么、输出是什么哪些环节该脚本化哪些环节需要 Agent 自主判断哪些操作必须有人工确认把这些想清楚Agent 就不再是“聪明但不可靠的实习生”而是“稳定且可交付的同事”。这才是“从会用 AI 到会开发 Agent”的真正含义。9. 下一步可以做什么这篇文章跑通了 Agent Skills 的完整链路概念、环境、技能创建、工具调用、排错和工程化建议。建议你先不要追求复杂的技能先照文中的示例创建一个脚手架技能在 Claude Code 或 Codex 里各调用一次验证闭环是否跑通。跑通之后再往两个方向深入。第一个方向是扩展技能覆盖面。把团队现有的开发规范、Review 清单、发版流程逐步转成技能包从一个技能扩展到一整套技能库。第二个方向是优化技能质量。观察 Agent 执行技能时有没有偏离步骤、有没有卡在脚本错误上不断修改SKILL.md里的描述和脚本里的细节。技能不是一次写完就结束的它和普通代码一样需要持续维护。如果后面要继续深入可以关注三个主题Agent 的工具调用机制、MCP 协议如何把外部系统接入 Agent、以及如何为 Agent 设计多步自主执行流程。每一块都值得单独写一篇实践文章。