如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

构建技能

使用插件的 MCP 工具构建可重复执行的工作流。

技能与 MCP 服务器相辅相成。技能指导 ChatGPT 和 Codex 如何在可重复执行的工作流中使用服务器提供的工具。使用服务器获取实时数据、进行身份验证和授权,以及执行受控操作。在技能中说明工具的调用顺序、何时需要做出选择以及输出要求,并提供示例、模板和其他可复用的指导。

一个插件可以包含一项技能,也可以包含一组相关技能。每项技能都应聚焦于用例清单中一个明确的用户目标。如果工作流只需要随技能打包的指令和资源,技能也可以独立于 MCP 服务器运行。

创建技能

最快的入门方式是使用内置的技能创建工具。请描述用户目标,并指出实现该目标所需的 MCP 工具:

@skill-creator Create a skill named tabletop-dice that understands dice
notation such as 3d6, calls roll_dice once for each die, and reports every
roll and the total.

在 Codex 中使用 $skill-creator 调用同一个创建工具。

您也可以手动创建文件。每项技能都放在单独的目录中,且必须包含一个 SKILL.md 文件:

  • skills
    • tabletop-dice
      • SKILL.md 必需的指令和元数据
      • references 可选的文档
      • scripts 可选的可执行代码
      • assets 可选的模板和资源

编写 SKILL.md

在文件开头填写名称和描述,然后编写指令:

---
name: tabletop-dice
description: Roll one or more dice for tabletop games and report each result and the total.
---

Use this skill when the user asks to roll dice.

1. Parse requests written as `NdS` as N dice with S sides. For example, `3d6`
   means three six-sided dice.
2. Call `roll_dice` once for each requested die and pass S as `sides`.
3. Report each tool result in order.
4. When the user requests multiple dice, add the results and report the total.

Do not invent, replace, or reroll a result unless the user asks you to.

描述决定模型何时考虑使用这项技能。请在描述中说明工作流的用途和触发条件,在正文中详细说明操作步骤、格式要求和安全要求。

明确工作流的适用范围

将每项技能与一个或多个用例关联起来。指令应明确说明:

  • 工作流需要哪些输入。
  • 模型应遵循哪些步骤。
  • 用户应收到什么输出。
  • 哪些事实模型不得自行推断。
  • 在什么情况下应向用户提问、停止执行或拒绝请求。
  • 模型应查阅哪些辅助文件。

每项技能应聚焦于一个目标,避免把大量关联不大的指令放在一起。如果工作流的触发条件、输入或成功标准不同,请将它们拆分开来。

检查模型能否遵循指令

为 GPT-6 Astra 编写或导入技能时,请参阅有关模型遵循指令的指南。检查技能及其辅助文件中是否存在含糊或相互冲突的指令,并写清楚用户明确给出的指令优先于技能指南。

添加辅助资源

保持 SKILL.md 简洁,将详细资料放在同一目录下:

  • 使用 references/ 存放策略、模式定义、示例和背景资料。
  • 使用 assets/ 存放工作流需要复制或转换的模板或文件。
  • 如果工作流需要执行确定性计算或处理文件,请使用 scripts/ 存放脚本。

在 SKILL.md 中引用辅助文件,并说明何时加载或运行这些文件。如果依靠指令和现有工具就能可靠地完成任务,请勿添加脚本。

将技能与 MCP 工具连接起来

技能可以指导模型使用插件的 MCP 服务器提供的工具。使用技能提供工作流指令,使用服务器获取实时数据、进行授权和执行受控操作。

如果技能需要 MCP 服务器,请在 agents/openai.yaml 中声明依赖项:

dependencies:
  tools:
    - type: "mcp"
      value: "dice-roller"
      description: "Roll an N-sided die"
      transport: "streamable_http"
      url: "https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp"

声明依赖项可以让模型访问所需的工具,您仍需编写清晰的工作流指令。请告诉模型要使用哪些工具、按什么顺序调用,以及如何处理结果缺失或含糊不清的情况。

测试技能

使用用例清单中的代表性请求进行测试:

  1. 应触发技能的直接请求。
  2. 间接表达相同目标的请求。
  3. 信息不完整、需要模型进一步提问的输入。
  4. 不应触发技能的请求。
  5. 模型必须避免编造信息或执行不受支持的操作的边界情况。

同时检查技能是否在恰当的时机触发,以及输出质量如何。如果技能在不恰当的时机触发,请调整描述。如果模型选择了正确的工作流,但输出结果不一致,请调整指令。

打包技能

在插件清单中指定技能目录:

{
  "name": "dice-roller",
  "version": "1.0.0",
  "description": "Roll dice for tabletop games",
  "skills": "./skills/",
  "apps": "./.app.json"
}

有关完整的清单、MCP 服务器映射、本地测试和分发流程,请参阅打包插件。