第6章 6-2 Codex Skills 搭建与使用

CodexSkills搭建与使用AgentSkills多平台应用实战·第6章第2节课程目录01核心原理深入理解从一次性指令到可复用工作流的核心逻辑与架构设计。02实战案例手把手教你创建「获取加密货币价格」Skill，掌握开发全流程。03对比分析深度解析CodexSkills与传统Prompt工程的优劣及适用场景。04常见问题与调试盘点开发与调试中常见的疑难杂症，提供高效的排查与解决技巧，助力开发少踩坑。05总结与实践任务回顾课程核心知识点，梳理关键收获，并布置课后实操任务，巩固学习成果。核心原理：从一次性指令到可复用工作流图示直观对比了Prompt与Skills的核心差异：前者是单次的指令传递，后者是固化的流程封装。这种转变让AI能力从“临时调用”升级为“可沉淀的组织资产”。01传统PromptEngineering：一次性沟通本质：基于自然语言的单次对话交互，依赖人工精心设计的指令。

局限：灵活性高但复用性差，每次任务都需重新构造提示词，难以沉淀为团队通用能力，效率随任务复杂度下降。02CodexSkills：模块化的工作流封装本质：将任务的触发条件、执行步骤、工具调用与输出格式打包为独立的“技能模块”。

价值：一次封装，多次复用，可维护、可共享，将个人经验转化为团队可复用的技术资产，显著提升协作效率。💡核心洞察：提示词是“把意图说出来”，而Skills是“把流程留下来”，实现从单次交互到长效资产的跨越。核心原理：架构运行机制CodexSkills构建在OpenAI成熟的AgentLoop之上，并对其进行结构化增强，形成高效、智能的任务处理闭环，实现从意图理解到结果交付的全流程自动化。01用户输入与解析用户发起具体任务请求，系统接收并初步解析任务的核心意图、目标及关键约束条件。02技能发现与匹配基于解析后的意图，检索技能库（SkillLibrary），通过语义匹配算法找到最适配的执行技能。03智能上下文构建整合技能定义、用户历史对话、当前输入及环境信息，构建结构化的Prompt上下文。04推理决策模型基于上下文进行推理，智能判断是否需要调用外部工具、API或执行代码脚本。05技能执行运行时环境解析指令，执行预定义的脚本逻辑，调用外部服务或操作系统命令。06结果反馈循环执行结果返回给大模型，触发新一轮的推理判断，形成闭环直至任务条件满足。07最终输出模型整合所有执行结果，生成自然语言化的最终响应，任务完成并反馈给用户。核心原理：架构运行机制示意图01用户输入UserInput02技能发现与匹配SkillDiscovery03上下文构建ContextConstruction04大语言模型(LLM)智能决策与推理中枢生成回答/判断工具调用直接输出结果DirectOutput生成自然语言回复05工具调用决策ToolCallDecision06技能执行SkillExecution07结果返回ResultFeedback2.实战案例：创建「获取加密货币价格」Skill01.定义Skill元数据(SKILL.md)name:get-crypto-price

description:"获取指定加密货币的当前市场价格，用户询问时触发。"

parameters:

type:object

properties:

symbol:

type:string

description:"币种符号，如'BTC'/'ETH'"

required:true通过结构化的Markdown文件定义Skill的基础信息、参数约束与触发条件，是Skill的“数字身份证”。Step1:参数校验与解析校验用户输入的`symbol`参数是否合法且非空，确保后续脚本调用的有效性，避免运行时错误。Step2:执行脚本获取数据调用`scripts/get_price.py`脚本，传入币种符号，从交易所API实时拉取最新的市场价格数据。Step3:结果格式化与反馈解析脚本返回的JSON数据，将价格信息转化为自然、易懂的语言，友好地呈现给用户，完成交互闭环。2.实战案例：创建「获取加密货币价格」Skill02/实现核心脚本逻辑在项目的`scripts`目录下创建`get_price.py`文件，作为Skill的核心执行单元。该脚本接收加密货币符号（如BTC、ETH）作为输入参数，通过调用公开的CoinGeckoAPI获取实时价格数据，并将结果以标准的JSON格式返回，确保与上层应用的兼容性。get_price.py—Pythondef

get_crypto_price(symbol):id_map={

'BTC'

:

'bitcoin'

,

'ETH'

:

'ethereum'

}c_id=id_map.get(symbol.upper())ifnot

c_id:

return

{

"error"

:

"Unsupportedcoin"

}try:url=

f"/api/v3/simple/price?ids={c_id}&vs_currencies=usd"res=requests.get(url)price=res.json()[c_id][

'usd'

]return

{

"price"

:price,

"source"

:

"CoinGecko"

}except

Exceptionase:return

{

"error"

:

str(e)

}💡环境准备：执行脚本前，请确保已安装依赖库：pipinstallrequests，并确保网络环境可访问外部API。2.实战案例：创建「获取加密货币价格」Skill通过CodexCLI界面，您可以直观地与技能进行交互。无论是输入命令行参数还是自然语言提问，都能快速获取实时加密货币价格，实现无缝的开发者体验。01赋权执行`chmod+x`命令，赋予脚本可执行权限，确保系统能够正确运行该文件。02部署将技能文件夹复制到Codex技能目录（如`~/.agents/skills/`），完成环境集成。03调用支持显式命令参数调用，或自然语言隐式交互，灵活适配不同使用场景。快速调用示例$codexexec"$get-crypto-price--symbolBTC"#显式指定参数调用，精准高效$codexexec"比特币现在多少钱？"#自然语言交互，更人性化的体验预期输出：

“比特币(BTC)的当前价格约为65,000.00美元。数据来源：CoinGecko。”3.对比分析：CodexSkillsvs.传统Prompt✨CodexSkills：高效、可扩展的开发范式📉传统Prompt：零散、维护成本高的临时方案⚡开发效率跃升✅一次定义，无限复用，告别重复造轮子

❌传统模式需反复调试，耗时费力且低效🛡️安全可控性✅内置权限校验与输入清洗，风险可控

❌易受提示词注入攻击，缺乏安全边界🧩复杂任务驾驭✅擅长多步骤、流程化、长逻辑链任务

❌仅能处理简单、独立的一次性查询需求📚团队资产沉淀✅转化为团队共享技能库，持续迭代优化

❌局限于个人经验，难以复用与传承📦上下文高效管理✅渐进式信息披露，精准控制Token消耗

❌冗长提示词占用大量Token，成本高昂🤝协作效率提升✅统一标准接口，多人协同开发更顺畅

❌风格各异难以对齐，沟通与磨合成本高核心洞察：

CodexSkills实现了从“一次性提示词编写”到“工程化技能构建”的质变。它不仅解决了传统Prompt维护难、复用低的痛点，更通过标准化、组件化的方式，让AI能力真正成为企业可沉淀、可扩展、可协同的技术资产，为规模化AI应用落地扫清障碍。4.常见问题排查01.Skill不生效或无法触发原因：

路径配置错误、SKILL.md格式不符合规范、触发词未精准匹配。排查：

核对文件路径与YAML语法，使用显式调用命令直接测试触发效果。02.Schema验证失败原因：

parameters字段的JSONSchema定义不符合JSON规范或平台校验规则。排查：

检查Schema语法合法性，使用在线JSONSchema校验工具验证结构。03.权限错误或脚本执行失败原因：

脚本缺少执行权限、依赖库未安装、环境变量中缺失必要的API密钥。排查：

添加可执行权限(chmod+x)，本地运行脚本测试，检查环境变量配置。04.技能名称解析错误原因：

技能名称包含特殊字符（如英文句号"."），导致系统解析异常。解决：

将名称中的特殊符号替换为连字符（-）或下划线（_），避免解析冲突。5.总结与任务核心概念：可复用工作流CodexSkills是对FunctionCalling的高级封装，将业务逻辑抽象为标准化模块，实现能力的复用与快速调用。标准开发：三步闭环遵循「定义规范(SKILL.md)→编写实现脚本→安装与调用」的标准化流程，降低开发门槛与协作成本。核心价值：高效与安全具备极高的复用性与可维护性，内置安全校验机制，支持拆解并处理复杂的多步任务，提升系统稳定性。运行机制：智能增强基于AgentLoop实现自主决策与迭代，配合渐进式披露机制，确保任务执行的准确性与灵活性。课后实操任务：构建天气预报Skill请动手实现一个「查询指定城市未来3天天气预报」的Skill，完成从定义SKILL.md到编写调用脚本的全流程，体验技能封装的完整闭环。课后实操任务：天气查询Skill01.创建项目目录

新建`weather-forecast`文件夹作为技能根目录，初始化基础结构。02.编写定义文件(SKILL.md)

定义技能名称、描述及必填参数`city`，规范技能元数据。03.开发核心脚本逻辑

编写脚本调用OpenWeatherMapAPI，解析并处理未来3天天气数据。04.配置环境与安装

配置API密钥环境变量，赋予脚本执行权限并安装至系统技能库。05.验证与测试调用

通过CLI进行显式调用与隐式语义匹配测试，确保功能稳定。作业验收标准(满分100%)2