agent skills是一个包含指令、脚本和资源的文件夹，agent可以发现并使用它们来更准确、更有效地做事。

使用agent skills以特定任务的能力扩展codex。技能包含了说明、资源和可选脚本，使Codex能够可靠地遵循工作流程。您可以跨团队或与社区共享技能。

agent skill的定义

skill是通过SKILL.md文件中的markdown指令来获取能力的。

my-skill/
  |-SKILL.md       Required: instructions + metadata
  |-scripts/       Optional: executable code【支持的语言取决于agent的实现。常见选项包括Python、Bash和JavaScript。】
  |-references/    Optional: documentation【包含agent可以在需要时读取的附加文档】
  |-assets/        Optional: templates, resources【包含静态资源】

技巧使用渐进式公开来有效地管理上下文。在启动时，Codex加载每个可用技能的名称和描述。Codex可以通过两种方式激活和使用技能：

• 显式调用：在提示词中直接包含技能。要选择一项技能，可以运行/skills斜杠命令，或者开始输入 $ 来提到一项技能。Codex网站和iOS还不支持显式调用，但你仍然可以要求Codex使用任何签入repo（作用范围）的技能。

• 隐式调用：当你的任务符合技能描述时，codex可以决定使用可用技能。

skills保存在哪里

Codex从这些地点装载skills。技能的位置定义了它的作用范围。

当Codex从这些位置加载可用技能时，它会覆盖优先级较低的范围中具有相同名称的技能。下面的列表显示了技能范围和位置的优先顺序（从高到低）。

Skill Scope	Location	Suggested Use
REPO	$CWD/.codex/skills，当前工作目录：启动Codex的位置。	如果您在存储库或代码环境中，团队可以检入与工作文件夹相关的技能。例如，只与微服务或模块相关的技能。
REPO	$CWD/../.codex/skills，在Git存储库中启动Codex时，CWD父文件夹中的。	如果您在具有嵌套文件夹的存储库中，可以签入在父文件夹中共享区域的技能。
REPO	$REPO_ROOT/.codex/skills，在Git存储库中启动Codex时最顶层的根文件夹。	如果您在具有嵌套文件夹的存储库中，组织可以检入与使用该存储库的每个人相关的技能。这些作为根技能，存储库中的任何子文件夹都可以覆盖它们。
USER	$CODEX_HOME/skills，（macOS和Linux默认：~/.codex/skills）所有的技能都记录在用户的个人文件夹中。	用于管理与用户相关的技能，这些技能适用于用户可能使用的任何存储库。
ADMIN	/etc/codex/skills，在共享的系统位置签入机器或容器的任何技能。	用于SDK脚本、自动化和检入机器上每个用户可用的默认管理技能。
SYSTEM	与codex捆绑在一起。	与广泛受众相关的有用技能，如技能创造者和计划技能。当他们开始Codex时，每个人都可以使用，并且可以被上面的任何层覆盖。

skill的好处

• 技能让团队获取机构知识，并将其转化为可重用、可共享的工作流。技能帮助Codex在用户、存储库和会话之间保持一致的行为，这在您希望自动应用标准约定和检查时特别有用。典型用例包括：

  • 标准化代码审查检查表和约定

  • 执行安全性或遵从性检查

  • 自动化常见的分析任务

  • 提供Codex可以自动发现的团队专用工具

创建skill

1. 使用 skill creator

Codex中内置的$skill-creator技能。描述你想要你的技能做什么，Codex将开始引导你的技能。

1. 手动创建 skill

1. 选择位置（repo-scoped 或者 user-scoped）

# User-scoped skill (macOS/Linux default)
mkdir -p ~/.codex/skills/<skill-name>

# Repo-scoped skill (checked into your repository)
mkdir -p .codex/skills/<skill-name>

2. 创建 SKILL.md 文件

---
name: <skill-name>
description: <what it does and when to use it>
---

<instructions, references, or examples>


3. 重启codex，加载skill

遵循最佳实践

• 明确触发器。描述告诉Codex何时触发技能。

• 保持技能小。比起大型技能，更喜欢狭窄的模块化技能。

• 比起脚本，更喜欢指令。只有在需要确定性或外部数据时才使用脚本。

• 不要假设语境。写指令时，仿佛法典委员会除了输入之外什么都不知道。

• 避免模棱两可。使用命令式、循序渐进的语言。

• 测试触发器。验证示例提示是否按预期激活技能。

SKILL.md的格式

• frontmatter ，SKILL.md文件必须包含YAML正面内容，然后是Markdown内容。

---
name: pdf-processing  【必填，最多64个字符。只能使用小写字母、数字和连字符。不能以连字符开头或结尾。】
description: Extract text and tables from PDF files, fill forms, merge documents.【必填，最大1024个字符。描述该技能的作用和使用时间。】
license: Apache-2.0  【非必填，License名称或对捆绑License文件的引用。】
metadata:   【非必填，用于附加元数据的任意键值映射。】
  author: example-org
  version: "1.0"
compatibility: Requires git, docker, jq, and access to the internet 【非必填，最多500个字符。说明环境需求（预期产品、系统包、网络接入等）。】

---

• Body content，正文后的Markdown正文包含技能说明。没有格式限制。写下任何有助于agents有效执行任务的内容。建议部分:

  • 一步一步的指示

  • 输入和输出的示例

  • 常见边缘情况

示例1

---
name: draft-commit-message
description: Draft a conventional commit message when the user asks for help writing a commit message.
metadata:
  short-description: Draft an informative commit message.
---

Draft a conventional commit message that matches the change summary provided by the user.

Requirements:

- Use the Conventional Commits format: `type(scope): summary`
- Use the imperative mood in the summary (for example, "Add", "Fix", "Refactor")
- Keep the summary under 72 characters
- If there are breaking changes, include a `BREAKING CHANGE:` footer

触发skill

Help me write a commit message for these changes: I renamed `SkillCreator` to `SkillsCreator` and updated the sidebar.