guard-skills

概览

GitHubGitHub

guard-skills 是一组面向 AI 编程代理的质量门控技能（skills），用于在代码、测试和文档被提交或合并之前，对 AI 生成的内容进行二次审查。 ## 它解决什么问题 AI 编程代理在生成代码时存在一些系统性的失败模式，例如过度抽象、吞掉错误、幻觉 API、测试膨胀以及文档与代码不一致等。guard-skills 作为反应式审查步骤，在代理完成工作后对 diff 进行检查，拦截这些问题。 ## 主要能力 该仓库包含五个独立的 guard 技能： - **clean-code-guard**：适用于任何语言的生产代码，检查 LLM 常见的代码异味、过度抽象、宽泛的错误捕获、命名问题以及 SOLID/DRY/KISS/YAGNI 违规。 - **test-guard**：适用于测试代码，支持 pytest、PHPUnit/Pest、Jest/Vitest、Go tests 等框架，检查 mock 滥用、重复测试、断言实现细节等问题。 - **docs-guard**：适用于 README、API 文档、docstring、changelog 等，将文档视为一系列声明并对照代码库验证，检查幻觉符号、损坏的示例和文档漂移。 - **wp-guard**：针对 WordPress 插件、主题、REST 端点、AJAX 处理器等，检查转义、清理、nonce、权限、预准备查询、i18n 和缓存问题。 - **woo-guard**：针对 WooCommerce 扩展、结账、订单和产品逻辑，建立在 wp-guard 之上，检查 HPOS 兼容性、直接 order meta 访问、金额处理等问题。 ## 适合谁 适合使用 Claude Code、Codex、Cursor、OpenCode 等 AI 编程代理的开发者。最佳实践是让代理先完成工作，然后在展示、提交或合并之前调用相应的 guard 对 diff 进行审查。 ## 技术特点 每个技能由一个 `SKILL.md` 入口文件、轻量级代理元数据和渐进式披露的参考文档组成。不包含可执行脚本、网络调用、MCP server 依赖或凭据，内容完全可检查。通过 Skills CLI 安装和管理。

Q&A

如何安装 guard-skills？由 AI 生成

使用 Skills CLI 安装。安装全部：`npx skills add amElnagdy/guard-skills`。安装单个：`npx skills add amElnagdy/guard-skills --skill clean-code-guard`。也可以指定代理：`--agent codex`，或全局安装：`--global`。

应该在什么时候使用这些 guard？由 AI 生成

最佳用法是让代理先完成工作，然后在展示、提交或合并之前，对生成的 diff 调用相应的 guard 进行审查。也可以在编写时显式要求 guard 约束生效，但它们作为反应式审查步骤效果最强。

如何更新已安装的 skills？由 AI 生成

Skills 以副本形式安装，新版本不会自动同步。使用 `npx skills update` 更新全部已安装的 skills，或使用 `npx skills update clean-code-guard` 更新特定 skill。重新运行 add 命令也会拉取最新版本。

支持哪些 AI 编程代理？由 AI 生成

支持 Claude Code、Codex、Cursor、OpenCode 以及其他通过 Skills CLI 支持的代理。

这些 skills 包含可执行代码吗？由 AI 生成

不包含。Skill 内容是 Markdown 加上轻量级的 agents/openai.yaml 元数据，没有可执行脚本、网络调用、MCP server 依赖或凭据。

wp-guard 和 woo-guard 有什么区别？由 AI 生成

wp-guard 覆盖 WordPress 层面的安全检查（转义、nonce、权限等）。woo-guard 建立在 wp-guard 之上，专门处理 WooCommerce 特有的问题，如 HPOS 兼容性、CRUD 替代直接 meta 操作、结账验证和金额处理。