create-verification-skill

创建验证技能

以粗体或反引号标出的技能名称，或以 /<name> 形式运行的技能，是此技能目录旁边的 ../<name>/SKILL.md 文件；未带前缀的原则名称对应 ../principle-<name>/SKILL.md。读取该文件并遵循其中的要求。大多数 pstack 技能仅供用户使用，因此你的技能工具无法加载它们。

每个严肃的项目都需要一种脚本化方式来驱动真实应用并验证其行为：启动应用，像用户一样操作某项功能，并捕获证据。此技能会生成一个适用于该仓库的项目本地技能（.agents/skills/verify-<app>/，并从 .claude/skills/verify-<app> 链接到该技能）。你编写的是供下一个 Agent 使用的生成结果，而非面向人类的说明：下一个 Agent 会在任务进行到一半时首次读到它，此前从未接触过该应用。

1. 了解仓库，而非询问用户

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

• 界面： 用户实际操作的是什么？Web UI、CLI/TUI、桌面应用、API、移动应用，还是库？一个仓库可能包含多种界面；选择主要界面，并注明其他界面。
• 运行： 如何在本地启动应用？优先采用仓库自身文档中的开发命令（package 脚本、Makefile、README 快速入门）。注明端口、环境变量、种子数据和身份验证信息。
• 操作： Agent 如何以编程方式与应用交互？优先使用现有测试工具——Playwright/Cypress 测试、expect 脚本、PTY 辅助工具、可通过 curl 访问的端点、调试端口等。之后再选择通用方案：Web UI 使用 preview_* 工具（录制视频时使用 preview_recording_start / preview_recording_stop）；Electron 使用调试端口上的 CDP；iOS 和 Android 模拟器使用 device_* 工具；CLI/TUI 在 shell 中使用 tmux/PTY 测试工具；服务则使用普通 HTTP。
• 观察： 可以捕获哪些证据？屏幕截图、终端记录、响应正文、日志、退出代码、数据库状态等。
• 隔离： 能否并行运行两个实例（端口、数据目录、配置文件）？如果不能，请在生成的技能中说明：拒绝同时驱动共用实例，也好过损坏用户会话。

如果当前检出的代码无法构建或启动，应先修复（或准确报告问题），再生成技能；基于损坏的基础编写技能会教错步骤。如果某个无关的缺失资源阻碍了启动（例如 API 从不提供服务的静态目录、示例配置），生成的技能可以创建该资源，但必须明确标记为验证辅助材料，并在清理时将其移除。

2. 生成技能

创建实际目录 .agents/skills/verify-<app>/ 和相对符号链接 .claude/skills/verify-<app> -> ../../.agents/skills/verify-<app>，这样 Claude Code 和 Codex 对话线程都会加载它。将两者都提交。将 SKILL.md 写入该目录，并添加 YAML frontmatter（name: verify-<app>，以及一条说明应用、界面和适用时机的 description——没有 frontmatter，技能就不会注册）和以下各节。每节都必须以访谈实际发现的内容为依据（不能留下占位符）：

• Launch： 启动应用以进行验证的确切命令，以及如何判断应用已就绪（日志行、提示符）。从空数据目录启动时，必须能进入可用状态，包括运行任何迁移并填充种子数据。就绪意味着可以使用，而不只是进程有响应。数据库健康检查可能会在初始化脚本仍在运行时就通过。说明如何 teardown。对于短生命周期 CLI 或 TUI，不需要保持服务运行：Launch 意味着构建一次二进制文件（或安装依赖），然后在各自隔离的 PTY 或 tmux 会话中启动每次操作。
• Doctor： 一个只读检查，用于回答“这个实例是否值得操作？”——进程是否运行、版本或构建是否正确、端口是否由我们占用、身份验证是否有效。只要出现任何异常，Agent 就会先运行此检查。
• Drive： 使用本仓库中真实选择器或命令的测试框架操作方法，而非示例。优先使用稳定标识（ARIA 标签、数据属性、提示字符串、路由路径），而不是坐标和 Tab 键顺序。
• Evidence： 说明要为证明捕获哪些内容，以及保存位置。明确证明标准：走实际用户路径，而不是内部 setter 或仅供测试使用的端点；捕获操作和产生的状态，而不只是最终屏幕；验证可见内容之外的副作用（写入的文件、插入的行、发送的消息）；仅在生产边界已隔离外部系统时使用 mock。如果安全路径是 dry-run 或测试模式，要通过观察（文件、网络、Git 引用）确认它实际跳过了什么，而不是相信它的名称：有些 dry-run 仍会访问网络或打开浏览器。
• Cleanup： 说明如何 teardown 本次运行创建的实例。绝不能按进程名称终止；只终止你启动的进程。Cleanup 要移除实例和临时状态，不能删除证明材料：证明产物必须在 teardown 后保留，并存放在技能指定的位置。
• Helpers： 技能附带的任何脚本都必须可执行，并且技能正文中要展示其调用方式。需要读者自行逆向分析的脚本算不上 helper。

3. 填充功能地图

在生成的技能目录中创建 features/README.md，并为你能识别的每项面向用户的功能创建一个文件（先以 3–5 项为目标，从路由、命令、菜单或文档中识别）。遵循 references/feature-map-example/ 中的结构，包含 README 索引和每项功能对应的文件。每个文件都要从用户的角度说明：功能是什么、如何访问、如何使用测试框架操作，以及哪些可观察到的最终状态可以证明功能正常。四个 H2 标题分别为 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。如果种子数据缺少某条用户操作路径所需的前置条件，该路径应报告失败，并在对应功能的 Gotchas 中说明原因。绝不能为了让路径通过而降低要求。功能地图是仓库维护的验证依据；当地图列出了其他入口点时，只验证一个方便的入口点并不完整。

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

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

5. 提供维护流程

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