Skills 与 SKILL.md

返回 Codex 教学总目录

读完能做到什么

Skill 适合把会反复使用的工作流程整理成可重用指引，例如每次改完待办网站后的验收。不要把所有专案规则都移过来：AGENTS.md处理持续适用的专案要求，Skill 则针对特定任务被选用。Plugins 可用来分发技能与连接服务，详见插件教学。

开始之前

准备已登入的 Codex CLI 或支援 Skills 的桌面／IDE 入口，并下载待办网站教材。本篇先复制 expected 为 codex-practice；再保留 broken 作为稍后的独立故障练习，不要把两个版本的档案混在一起。

测试使用 Node.js，浏览器预览使用 Python 3。没有浏览器工具时，技能应回报画面检查未执行，提供给你手动操作的步骤；不能因为写了「检查画面」就假设环境会自动多出工具。你也可以下载完整技能范例，先阅读再放入练习专案。

最少必要概念：名称、描述与内容

一个技能至少是一个资料夹与其中的 SKILL.md。档案开头用 YAML frontmatter 保存 name 和 description，正文才是执行流程。Codex 先看到名称与描述，决定使用后才读完整内容，所以「什么都帮忙」之类的描述很容易在不适合的任务被选中。

本例的名字是 todo-acceptance，描述把范围限定为 Small Steps 的验收，而不是任意网站开发。先保持纯指引，不加脚本、外部服务或全域安装。只有需要稳定重复的工具逻辑时，再将程式放进 scripts；大量参考资料可以另放 references 并在主文件指出何时读取。

第一步：建立专案内的技能位置

从 codex-practice 根目录建立 .agents/skills/todo-acceptance。前面的点是资料夹名称的一部分；不是 .codex，也不是 agents 少一个点。Windows PowerShell 可执行以下命令；已存在时先看内容，不要覆盖别人的技能。

New-Item -ItemType Directory -Force .agents/skills/todo-acceptance

mkdir -p .agents/skills/todo-acceptance

用纯文字编辑器建立 SKILL.md，Windows 检查不是 SKILL.md.txt，Linux 检查大写档名。完成后的目录如下。这个位置让技能和练习专案一起管理，不会立刻变成所有专案共用的个人技能。

codex-practice/
  index.html
  style.css
  app.js
  core.mjs
  core.test.mjs
  .agents/
    skills/
      todo-acceptance/
        SKILL.md

第二步：写入完整技能

以下内容与下载范例相同。流程会读现有程式、执行既有测试、在可用时检查浏览器，最后以 PASS、FAIL、NOT RUN 区分结果。它不会为了让验收通过而偷偷修程式，让你能先看懂实际问题再决定是否修改。

---
name: todo-acceptance
description: Verify the Small Steps todo practice website after a change, using its existing tests and browser checks. Use for acceptance checks of this exercise, not unrelated websites or feature implementation.
---

# Small Steps acceptance

Confirm the requested practice folder contains index.html, style.css, app.js,
core.mjs and core.test.mjs. If these are missing, stop and report the path checked.

Read the existing code, then run `node --test core.test.mjs` from that folder.
Do not rewrite tests or implementation to make an acceptance run pass.

If a browser is available, preview the site on a loopback address with a fresh
browser context. Add Read and Build, complete Read, check Active and Completed
filters, reload, and delete Read. Reject whitespace-only input. Check 390px and
1280px widths and visible Tab focus. Keep existing user browser data unchanged.

Report PASS, FAIL or NOT RUN for each check, with the command, observation or
limitation. Include the working folder and remaining issues. Do not claim that
tests, screenshots, deployment or publication happened without evidence.

If a check fails, report the reproduction and relevant file. If a required tool
is unavailable, report NOT RUN and the manual steps. Finish with results only;
implement fixes only when the user requests them.

name 适合用小写英文、数字及连字号，资料夹名称也保持相同。description 的触发边界写在前面，正文则保留真正会影响决策的条件。本例没有多余的套件或设定档；建立更多空资料夹不会让技能更完整。

第三步：找到技能并明确使用

Codex 会侦测技能变更；没有出现时重新开启工作阶段，确认工作目录位于此专案。CLI 或 IDE 可用 /skills 或输入 $ 寻找技能；桌面应用程式可由侧栏 Skills 检查可用项目，依目前介面选择。选单能找到名称，才是「已发现」的证据，仍不是已执行。

$todo-acceptance Check this Small Steps practice folder. Report the results without editing files.

桌面版若提供技能选择器，先选 todo-acceptance，再送出同样的验收要求。开始时请确认它读的是本专案 SKILL.md，而不是另一个同名技能。两个同名技能不会自动合并；全域或其他目录存在同名项目时，路径尤其重要。

第四步：核对正常与故障结果

在 expected 副本，node --test core.test.mjs 应有 3 个测试通过。回应应列出实际命令与结果；如果也执行浏览器流程，应能描述 Read、Build、筛选、重新整理及空白输入的结果。没有浏览器时应把该项列 NOT RUN，这不是测试通过也不是整个技能失效。

再建立一份独立 broken 副本，把同一个技能资料夹放到该副本的 .agents/skills，从那个位置建立新任务。这个版本刻意把 Completed 筛选反过来：Read 完成、Build 未完成时，会错误显示 Build。资料测试应为 2 个通过、1 个失败，技能应报告 FAIL 和重现方法，原始码维持不变。

这个比较能验证工作流程是否会忠实回报失败。档案格式检查只证明 YAML、名称与结构能解析，不证明代理真的照流程做；反过来，测试失败也可能正是技能成功找到问题。请分开保存这些证据，避免只有一个模糊的「成功」勾选。

再验证「材料不足就停止」

另外复制 expected 成一份独立的 incomplete 练习目录，放入同一份技能。先把这个副本的 core.test.mjs 移到该目录外的备份位置，保留原始 expected 与 broken 不变，再从 incomplete 开新任务选用技能。合格结果是指出缺少的档案与检查路径，停止后续验收；不能自行补写测试、改到另一份目录执行，或沿用先前的通过结果。完成后把备份放回原位置，再重新验收。

这与 broken 的差别是：broken 材料齐全、测试确实执行但失败；incomplete 尚不符合起步条件；没有浏览器工具则只让画面项目 NOT RUN。不要把三种情况都写成同一个 FAIL。要整理更多输入与触发情境，接著看技能测试；要加入脚本与参考文件，先看技能资源。

常见问题、停用与还原

技能没有出现：先检查 .agents/skills 的位置、SKILL.md 真正副档名、frontmatter 是否以两行 --- 包住，以及 name／description 是否存在。确认不是把整个 ZIP 放进资料夹后就以为已安装。修正后重开 Codex 再查选单。

技能出现却没使用：先明确选取或以 $todo-acceptance 指定，检查名称及来源路径。自动选用依描述与任务判断，不保证任何一句相似文字都会触发。若普通问候也经常触发，应收窄描述，让它只处理待办网站验收。

被选用却无法测试：确认 Node.js 在实际主机可用、目前目录含 core.test.mjs。从手机 Remote 使用时，技能与测试工具都在主机；电脑 A 装好不代表电脑 B 也有。不要让技能自行安装所有缺少的工具来掩盖环境条件。

停止进行中的验收先在任务内中止；需要停用时，将这份练习技能移出专案的技能扫描位置，保留备份，再重开工作阶段核对。更细的停用设定可以依官方 [[skills.config]] 说明处理，但要先保留既有 config.toml。停用不会删除之前的报告，也不会撤销任何过去修改。

小练习与验证纪录

比较两个提示词：「请验收 Small Steps 的筛选与储存」和「请解释今天的练习目标」。前者适合使用技能，后者不需要完整验收。记录选用与否、实际路径和结果，根据观察调整描述；不要把一次选对就当成所有情境都通过。

技能机制依 Build skills 官方文件于 2026-09-14 查证。范例会做格式验证，网站核心与故障结果已有实际测试；自动触发与不同 Codex 介面的选择器仍须分别实测，未列为全部通过。下一步可读插件、MCP及测试与审查。

返回 Codex 教学总目录

阅读完整文字说明

SKILL.md to Invoke to Output

• AI 工具
• 教程
• Codex