理解Codex技能与SKILL.md：让重复业务只需说明一次

摘要： 技能是为复用重复业务所需流程与结果格式而整理的集合。初次可先为一种任务编写简短SKILL.md。

1. 技能何时有用？

每次请求文档审查，都反复说明“查找过时命令、比较代码与说明、用表格整理结果”时，可以将其整理为技能。这比保存提示词更进一步，将使用时机、必要输入、处理流程与结果格式汇集起来。

OpenAI官方说明指出，技能汇集特定工作的指导与辅助资料，而插件是可安装的集合，可包含技能或连接工具等。因此存在技能名称，并不意味着一定具备连接外部服务的功能。应区分是否有流程，以及是否有实际可用工具。

2. SKILL.md的基本结构

官方编写文档建议在技能文件夹中放置SKILL.md，并包含name与description。必要时可添加脚本、参考资料与模板等。初次也可以不写执行代码，只编写工作指导。

---
name: docs-check
description: 프로젝트 문서의 명령과 경로를 검토하고 차이를 보고할 때 사용합니다.
---

프로젝트 문서 검토 지침

입력:
- 검토할 문서 경로
- 비교할 프로젝트 설정과 소스

수행:
1. 문서에 적힌 경로와 명령의 근거를 확인합니다.
2. 실제 프로젝트 설정과 다른 내용을 찾습니다.
3. 직접 확인한 사실과 추가 확인이 필요한 내용을 구분합니다.
4. 이 작업에서는 파일을 수정하지 않습니다.

출력:
- 문서 위치 / 차이 / 근거 / 권장 수정
- 검토하지 못한 범위

此示例是假想文档审查技能，并非介绍已安装或运行过的技能，因此应在真实项目中确认行为后再使用。若希望自动修改，还需另行设计该阶段与变更边界。

3. 在description中写明使用时机

“帮助开发的最佳技能”等描述，无法说明在哪种请求中应用。可写“比较README执行命令与项目配置时使用”等情况。有多个相似技能时，也宜区分文档审查与代码审查的范围。

正文应明确保留所需成果。如果目的是修改文档文体，重点可能是句子与读者，而非核对依据；查找代码与文档不一致，则重点是路径与配置。先从一项明确任务开始，比把不同业务都放入巨大技能更容易评价结果。

4. 加载后确认是否按预期工作

官方文档说明，可在Codex中明确选择技能，或在请求符合描述时自动应用。CLI与IDE应确认$提及等对应环境的选择方式。本地技能路径也应遵循当前官方指南，不能假设旧文章中的位置始终不变。

$docs-check
README.md의 실행 안내를 검토해 주세요.
package.json과 관련 설정을 근거로 비교하고,
문서 위치, 차이, 근거, 권장 수정을 표로 정리해 주세요.
파일은 수정하지 말고 미확인 사항을 표시해 주세요.

首次使用应确认技能是否读取必要文档、是否按约定格式输出，以及是否进行了禁止的修改。也应检查是否声称实际读取了不存在的文件。结果偏离时，宜补充造成错误判断的部分，而不是一次扩充大量指导。

5. 技能未按预期应用时

• 未被选择： 检查安装状态与描述是否符合实际请求。
• 与其他技能混淆： 区分名称与适用范围。
• 指导范围过宽： 将输入、完成标准与结果格式对应到一项业务。
• 无法读取外部资料： 分别确认技能指导与实际工具、访问权限。
• 结果难以比较： 在输出中包含依据位置与未确认范围。

引入他人技能时，应检查指导及包含的脚本。复用特定业务指导，与扩大执行权限，是不同决定。初次针对能以草稿形式审查结果的任务设计，更容易确定检查标准。

6. 在项目中放置首个技能

首个文档审查技能放在项目内，便于共同管理指导与代码变更。当前官方文档介绍了仓库中.agents/skills路径的本地技能发现机制。下方是在仓库根目录放置docs-check技能的示例。上级文件夹与用户范围也可能存在技能，应先检查是否已有同名技能。

project/
  .agents/
    skills/
      docs-check/
        SKILL.md
  README.md
  package.json
  docs/

Windows PowerShell可用下方命令准备文件夹。先确认位于项目根目录，再将前节指导保存到创建文件夹中的SKILL.md。该命令是创建技能文件夹的示例，并不代表本文章实际安装后的结果。

Get-Location
New-Item -ItemType Directory -Force -Path '.agents\skills\docs-check'
Get-ChildItem -LiteralPath '.agents\skills\docs-check'

保存技能后，应确认当前客户端中能否选择。官方文档说明，Codex会检测技能变化，未显示更新时可重启。CLI可通过/skills或$提及直接选择。选择清单未显示时，应先检查文件名、name与description元数据，以及保存位置。扩充技能正文无法解决安装位置错误。

7. 使名称与描述符合业务范围

技能首先通过名称与描述判断适用于什么业务。即使正文流程优秀，如果描述只有“文档相关任务”，也难以区分写作、翻译、总结与审查中何种请求使用。描述中加入任务开始条件与排除业务，可以明确适用范围。

넓은 설명:
문서 작업을 도와주는 스킬입니다.

구체적인 설명:
README나 docs의 실행 명령·로컬 경로를
현재 프로젝트 설정과 비교해 오류를 보고할 때 사용합니다.
문체 수정·번역·외부 웹사이트 전체 검사는 대상으로 하지 않습니다.

实际description应在YAML元数据中使用正确字符串格式。宜让“何时使用、哪些工作不做”先被读到，而不只是增加长度。与其创建多个相似名称，不如采用docs-check等能看出职责的名称；已有同名技能时，可选其他名称。官方文档说明，同名技能不会自动合并。

正文应保留需要判断的选择。“确认所有链接”可能让本地路径与外部URL采用同一方法。本地路径检查仓库中是否存在，外部URL则先区分当前任务能否访问网页。外部检查不在范围内时，可标注未检查。结果格式应确定空白的含义，避免将未访问资料报告为正常。

8. 将文档审查转化为有依据的报告

假设假想README写着npm run start，但当前package.json只有dev与test。应区分“start不存在”的事实与“可改为dev”的建议。审查开发服务器指南时，dev可能是候选；若是生产服务器指南，则可能需要其他命令与构建流程。不能只因脚本名称相似就直接替换。

문서 검토 세부 절차
1. 문서에서 실행 명령과 로컬 파일 경로를 추출합니다.
2. 실행 명령은 해당 프로젝트 설정과 README 맥락을 함께 비교합니다.
3. 경로는 문서가 기준으로 삼는 폴더를 확인하고 존재 여부를 조사합니다.
4. 일치·불일치·미확인으로 구분합니다.
5. 불일치는 근거 파일과 필요한 수정안을 함께 보고합니다.
6. 판단 자료가 없으면 확인할 자료를 적고 문서를 임의로 수정하지 않습니다.

실패 분기
- 대상 문서 없음: 정확한 경로를 요청하고 검토 미실행으로 보고
- 설정 파일 없음: 다른 언어나 도구의 설정 위치를 조사
- 외부 링크 접근 불가: 실패와 미검사를 구분
- 명령의 목적 불분명: 개발·빌드·운영 중 용도를 확인

结果表需要位置与依据，人工才能修改。“README已过时”范围太广，难以确定下一行动。应将文档位置与判断联系起来，例如“开发服务器运行章节的start脚本不在当前配置中，应确认dev的作用”。未实际执行命令时，应区分脚本存在与运行成功。

9. 评价与修改技能的小案例集合

初次评价技能，不应只检查同一文档一次，可加入不同小情况。区分正常指南、不存在的命令、没有文档的请求与技能范围外请求，即可了解判断在哪里偏离。以下是评价输入与预期标准的示例，并非执行结果。

• 正常README：是否不会编造问题，并报告已确认依据？
• 不存在的脚本：是否区分未在配置中找到的事实与修改建议？
• 文档路径错误：是否避免读取其他文件后假装正常审查？
• 文体修改请求：是否与此技能的审查范围区分？
• 未访问外部资料：是否标为未确认，而不断定正常？

$docs-check
README.md의 개발 실행 안내와 로컬 설정 경로를 검토하세요.
문서 위치 | 일치 여부 | 실제 확인 근거 | 수정 제안 형식으로 보고하세요.
명령을 실행하지 않았다면 실행 성공으로 표현하지 마세요.
파일 수정은 하지 말고 필요한 다음 확인을 적어 주세요.

结果错误时，只补充对应错误部分的规则。如果无法读取外部URL却报告正常，添加“标明外部资料未检查”即可。如果误解某脚本用途，则补充比较命令目的的流程。每次失败都添加冗长禁止句，可能反而遮蔽正常工作顺序。

流程稳定后再考虑辅助资料或脚本。制作供人工修改的表格，可以仅从指导开始；当大量文件中提取同一路径等重复计算变得明确，脚本可能有帮助。添加脚本后，应在技能文档中写明接收什么输入、修改哪些文件，让结果可审查。

10. 常见问题

创建技能会训练模型吗？ 本文章的技能是提供可复用指导与资料的方式，不应理解为单独训练模型的流程。

一定需要脚本吗？ 传递重复流程与结果格式的业务，可仅从指导开始。需要计算或外部工具时，再考虑添加。

项目规则也全部做成技能吗？ 区分适用于所有任务的共同规则，与仅特定业务需要的流程，更容易管理文档。技能应先包含选择该业务时需要的内容。

官方来源与确认日期： OpenAI官方文档：技能与插件 · OpenAI官方文档：构建技能。2026年10月3日确认。示例应按自己的项目与当前功能调整。