guard-skills: Second-Pass Quality Gates for AI-Generated Code, Tests, and Docs

The Problem guard-skills Addresses

Coding agents generate syntactically correct code that often carries a specific class of failure modes: catch-all error swallowing that returns a hardcoded success, hallucinated API calls that do not exist, tests that mock the agent's own state objects rather than external boundaries, documentation that references functions the codebase does not contain, and WordPress plugins that echo raw request data without sanitization.

The README states that guard-skills is not a full process framework and not a broad platform catalog. It is narrower: a set of reactive review passes run after the agent produces work. The README describes the intended usage as running the relevant guard on the diff before presenting, committing, or merging. The skills can also guide writing when invoked up front, but the README describes that as a secondary use.

The five guards address: production code in any language (clean-code-guard), test code in any language (test-guard), documentation of any kind (docs-guard), WordPress-specific code (wp-guard), and WooCommerce-specific code (woo-guard). The README's comparison table for each guard also lists what guard to pair it with: clean-code-guard pairs with platform-specific guards, test-guard pairs with clean-code-guard when test helpers contain real logic, and wp-guard pairs with woo-guard when WooCommerce APIs appear in the same diff.

Installing via the Skills CLI

The Skills CLI provides the install surface. To browse the package first:

npx skills add amElnagdy/guard-skills --list

To install the complete package:

npx skills add amElnagdy/guard-skills

Individual guards can be installed selectively:

npx skills add amElnagdy/guard-skills --skill clean-code-guard
npx skills add amElnagdy/guard-skills --skill test-guard
npx skills add amElnagdy/guard-skills --skill docs-guard

The --agent flag pins the install to a specific agent:

npx skills add amElnagdy/guard-skills --skill test-guard --agent claude-code

Global install is available with --global. Because skills install as a copy, updates to the upstream repository do not automatically reach a local install. Refreshing requires running npx skills update or npx skills update clean-code-guard for individual guards.

What clean-code-guard and test-guard Catch Specifically

clean-code-guard applies Clean Code, SOLID, DRY, KISS, and YAGNI principles to generated or changed code in any language. The README notes that it includes an AI-specific layer covering catch-all error swallowing, hardcoded success returns, hallucinated APIs, premature abstraction, comment pollution, and copy-from-similar bugs. The README references published research on duplication growth, package hallucination, and agents declaring success despite failed tests as justification for this layer.

test-guard targets generated or changed test code. Nine universal rules cover the most common AI test failures: mock only at system boundaries, never mock your own state objects, parametrize instead of copy-pasting test bodies, delete tests that catch nothing, and treat production regression tests as sacred. The README notes that framework-specific details are loaded progressively only when relevant to the test framework in use, covering pytest, PHPUnit and Pest, Jest and Vitest, Go tests, and WordPress and WooCommerce tests.

The README describes the effect: a generated test file with MagicMock() on state objects, duplicated test bodies, and log-message assertions comes back as do-not-merge with rule-by-rule fixes.

docs-guard, wp-guard, and woo-guard

docs-guard treats documentation as a list of claims and verifies each against the codebase. Its stated effect is that generated READMEs stop referencing functions that do not exist, @param tags match the real signature, and samples run on a clean machine. It covers READMEs, API references, docstrings, PHPDoc and JSDoc, changelogs, and tutorials.

wp-guard enforces the layer that generic clean-code guidance does not reach for WordPress: proper escaping and sanitization before output, nonce and capability checks on every write action, prepared database queries, use of core APIs before custom plumbing, translation-ready strings, and query and caching discipline. The README gives a specific example: generated plugins stop echoing raw request data, writing REST routes get real permission callbacks, and every string is translation-ready.

woo-guard sits on top of wp-guard and adds WooCommerce-specific rules: HPOS-safe order access using the CRUD API rather than direct meta, truthful feature-compatibility declarations, server-side checkout validation, money-handling discipline, and hooks over template overrides. The README notes that order code surviving HPOS and stock updates not racing are the tests of whether woo-guard had an effect.

How to Invoke the Guards and When Not To

The README gives example invocations as plain-text instructions passed to the agent:

Use $clean-code-guard on the diff you just produced.
Use $test-guard on the tests you just wrote.
Use $docs-guard on this README update before we ship it.

Invoking a guard up front, while the agent is writing, is documented as a secondary mode for cases where you want the constraint active during generation rather than only after delivery.

The README is clear about the boundary: guard-skills does not teach agents how to build across a platform the way a repository like WordPress/agent-skills does. It gives agents review gates to run after they have produced work. Teams that need agents to learn a platform's full API surface and idiomatic patterns should look elsewhere; teams that need a final check before the diff lands are the target.

License and Maintenance

The repository is licensed under MIT, which allows use, modification, and distribution with minimal conditions. The package is published at skills.sh/amElnagdy/guard-skills, and the install surface is the Skills CLI maintained separately.

The last push to the master branch was on 2026-07-04. The repository has no GitHub releases. The skill files live in the skills/ directory at the repository root. The README notes that skills install as a copy, so a new version pushed to the upstream repository does not reach a local install until npx skills update is run. Teams should refresh periodically:

npx skills update

Or update a single guard by name:

npx skills update clean-code-guard

Global installs require adding --global; project installs require --project. Re-running npx skills add amElnagdy/guard-skills also re-fetches the latest version of all guards in the package.

Editorial conclusion

Developers who use Claude Code, Codex, or Cursor to generate code and want a systematic second pass before committing or merging will find guard-skills directly applicable, particularly for WordPress and WooCommerce work where the wp-guard and woo-guard skills cover escaping, HPOS compatibility, and other platform-specific failure modes. Teams working outside WordPress should evaluate whether clean-code-guard and test-guard alone justify the install. The last push to the master branch was on 2026-07-04, so the skill content reflects that date.

Frequently asked questions

Official sources

1. amElnagdy/guard-skills on GitHub
2. Issues
3. License: MIT
4. Project website
5. README