create-verification-skill

创建验证技能

在 Codex 上，遵循此技能之前，请阅读平台映射，包括其中针对每项技能的说明。

在 GitHub Copilot 上，遵循此技能之前，请阅读平台映射，包括其中针对每项技能的说明。

在 Muse 上，遵循此技能之前，请阅读平台映射，包括其中针对每项技能的说明。

每个严肃的项目都需要一种脚本化方式来驱动真实应用并验证其行为：启动应用，像用户一样体验某项功能，并采集证据。此技能会根据代码库生成一项项目本地技能（.claude/skills/verify/）。将其命名为 verify。在代码库根目录中，同名的项目技能会取代 Claude Code 内置的 /verify（它只能由用户调用），因此所有指定了驱动技能的操作手册都可以调用项目技能（Claude Code 2.1.200 或更高版本）。在 monorepo 中，请将其写入被修改的包目录。你要为下一个 Agent 编写生成器的输出，而不是为人类编写：一个从未见过此应用的 Agent 会在任务进行到一半时直接读取它。

1. 访查代码库，而非用户

从代码库中找到以下问题的答案，只向用户询问你无法观察到的信息：

• 界面： 用户实际会接触什么？Web UI、CLI/TUI、桌面应用、API、移动应用还是库？代码库可能有多个界面；选出主要界面，并注明其他界面。
• 运行： 如何在本地启动应用？优先采用代码库自身文档中的开发命令（package scripts、Makefile、README 快速入门）。记录端口、环境变量、种子数据和身份验证信息。
• 驱动： Agent 如何以编程方式与之交互？先查找已有的测试框架——Playwright/Cypress 测试、expect 脚本、PTY 辅助工具、可通过 curl 调用的端点、调试端口。然后再选择通用方案：Web 和 Electron 使用 browser/CDP，CLI/TUI 使用 tmux/PTY 测试框架，服务使用纯 HTTP。
• 观察： 可以采集哪些证据？屏幕截图、终端记录、响应正文、日志、退出代码、数据库状态。
• 隔离： 两个实例能否并行运行（端口、数据目录、配置文件）？如果不能，请在生成的技能中说明：拒绝同时驱动共享实例，也好过破坏用户会话。

如果当前检出的代码无法构建或启动，请先修复（或准确说明问题）再生成技能；基于损坏的基础编写技能会教人错误的步骤。如果无关的缺失资源阻碍了启动（例如 API 从未提供服务的静态目录、示例配置），生成的技能可以创建这些资源，但必须明确标记为验证用脚手架，并在清理时移除。

2. 生成技能

编写 .claude/skills/verify/SKILL.md，包含 YAML frontmatter（name: verify，以及一段说明应用、界面和何时使用此技能的 description——没有 frontmatter，技能就永远不会注册；设置 disable-model-invocation 后，模型则无法调用它），并包含以下各节，每节都要基于访谈中的实际发现（不得遗留占位符）：

• **启动：**启动应用以进行验证的准确命令，以及如何判断应用已就绪（日志行或提示）。启动后必须从空数据目录进入可用状态，包括完成任何迁移并写入种子数据。就绪意味着可用，而不只是进程有响应。数据库健康检查可能会在初始化脚本仍在运行时就通过。还要说明如何停止。对于短时运行的 CLI 或 TUI，无需保持服务运行：启动意味着构建二进制文件（或安装依赖）一次，然后在各自隔离的 PTY 或 tmux 会话中启动每次驱动过程。
• **诊断：**一个只读检查，用来回答“此实例是否值得驱动？”——检查进程是否运行、版本或构建是否正确、端口是否由本实例占用、身份验证是否有效。任何情况看起来不对劲时，Agent 都先运行此检查。
• **驱动：**使用本仓库中的真实选择器或命令编写测试框架操作方案，不要用示例。优先使用稳定的定位方式（ARIA 标签、数据属性、提示字符串、路由路径），而不是坐标和 Tab 键顺序。
• **证据：**说明要为验证记录哪些内容，以及存放位置。明确证据标准：走真实用户路径，而不是调用内部 setter 或仅供测试使用的端点；记录操作及其产生的状态，而不只是最终画面；核验可见内容之外的副作用（写入的文件、插入的行、发送的消息）；仅在生产边界本身已隔离外部系统的情况下使用模拟。当安全操作路径是试运行或测试模式时，应通过观察实际行为（文件、网络、Git 引用）来核验其跳过了什么，而非仅凭名称判断：有些试运行仍会访问网络或打开浏览器。
• **清理：**说明如何停止本次运行创建的实例。绝不能按进程名称结束进程；只结束自己启动的进程。清理时移除实例和临时状态，但不得删除证据：证明材料必须在清理后保留，且技能中要注明其存放位置。
• **辅助工具：**技能附带的任何脚本都必须可执行，并在技能正文中展示其调用方法。需要读者自行逆向分析的辅助工具不算辅助工具。

3. 填充功能地图

创建 .claude/skills/verify/features/README.md，并为能识别出的每项面向用户的功能各建一个文件（先从路由、命令、菜单或文档中挑选最重要的 3–5 项）。遵循 references/feature-map-example/ 中的结构，包括 README 索引和每项功能对应的文件。每个文件都要从用户的角度回答：该功能是什么、如何进入、如何使用测试框架驱动，以及哪些可观察到的最终状态能证明它正常工作。四个二级标题必须为 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。如果种子数据缺少某次用户流程所需的前提条件，该流程应报告失败，并在对应功能的 Gotchas 中说明原因。绝不能为了让流程通过而降低标准。此地图是仓库维护的验证来源；如果地图列出了其他入口，只驱动一个方便的入口来提供证明是不完整的。

4. 交付前证明生成的技能有效

端到端运行一次技能自身的指令：启动、运行 doctor、驱动一个已映射功能（一个就够；这份映射是为了后续运行覆盖其余功能）、收集证据、清理。清理后，确认指定位置仍有证据——如果清理操作删除了证据，就不算通过此步骤。修复所有失败之处，并且每次迭代失败后都运行生成的清理操作，以免失败的尝试遗留进程和端口。未经实际运行的生成技能只是草稿，不是可交付成果。如果你是在真实目标的替代环境中验证的（例如用容器代替全新的 VM，用本地技术栈代替远程技术栈），请列出替代环境执行、而目标环境不会执行的所有设置步骤。在真实目标上运行并覆盖这些步骤之前，它们都仍未经过验证。

5. 提供维护流程

引导用户使用 /maintain-verification-skill，以便在应用发生变化时保持映射准确。只有在用户询问时，才建议维护周期。