amElnagdy/guard-skills: review gates for AI-generated code, tests and docs

What problem guard-skills solves, and who it is for

Coding agents produce code that compiles, tests that pass, and READMEs that read well, and all three can still be wrong in patterned ways. The README frames guard-skills as "second-pass quality gates that catch the systematic failure modes of AI-generated code, tests, and docs before they ship." The emphasis is on systematic: the same mistakes recur across projects, so a fixed checklist can catch them.

The intended workflow is reactive, not generative. The README states the best use is to let the agent do the work and then invoke the relevant guard on the diff before you present, commit or merge it. Skills can guide writing if you explicitly ask, but the documentation says they are strongest as review passes.

That positions the project for developers who already have an agent loop and are unhappy with what comes out the far end. It is not for teams looking for an agent framework, a linter, or a CI service. The target audience is narrower than the topic list suggests: the WordPress and WooCommerce guards are specific enough that a general web developer will install two of the five and ignore the rest.

Five guards, five different failure surfaces

The package ships five skills, each keyed to a kind of artifact rather than a language. clean-code-guard covers production code and adds an AI-specific layer the README says most rule packs miss: catch-all error swallowing, hardcoded success returns, hallucinated APIs, premature abstraction, comment pollution, and copy-from-similar bugs. It cites published research on duplication growth, package hallucination, and agents declaring success despite failed tests.

test-guard targets test code across pytest, PHPUnit/Pest, Jest/Vitest, Go tests and WordPress/WooCommerce tests. Nine universal rules are listed in the README, among them mocking only at system boundaries, never mocking your own state objects, parametrizing instead of copy-pasting, deleting tests that catch nothing, and treating production regression tests as sacred. Framework specifics live in progressive-disclosure references the agent loads only when relevant, including one for LLM applications.

docs-guard treats documentation as a list of claims to verify against the codebase. It covers READMEs, API references, docstrings, PHPDoc/JSDoc, changelogs and tutorials.

wp-guard and woo-guard are the platform pair. wp-guard handles plugins, themes, blocks, REST endpoints, AJAX handlers, shortcodes, WP-CLI commands and queries, enforcing escaping, sanitization, nonce plus capability checks, prepared queries, core APIs before custom plumbing, translation-ready strings, and query and caching discipline. woo-guard sits on top of it and covers HPOS-safe order access, CRUD over direct meta, feature-compatibility declarations, server-side checkout validation, money handling, and hooks over template overrides.

The README's own table pairs them: clean-code-guard pairs with platform-specific guards, test-guard with clean-code-guard when test helpers contain real logic, docs-guard with any guard whose behavior is documented, and wp-guard with woo-guard when Woo APIs appear.

Installing guard-skills and running your first guard

Installation goes through the Skills CLI. The README suggests browsing the package first so you can see what is inside before committing to it:

npx skills add amElnagdy/guard-skills --list

Installing the whole package is a single command:

npx skills add amElnagdy/guard-skills

If you only want one guard, the README shows the per-skill form. These are the exact skill names used in the repository's examples:

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
npx skills add amElnagdy/guard-skills --skill wp-guard
npx skills add amElnagdy/guard-skills --skill woo-guard

You can also target a specific agent. The README gives codex, claude-code and cursor as examples:

npx skills add amElnagdy/guard-skills --skill clean-code-guard --agent codex
npx skills add amElnagdy/guard-skills --skill test-guard --agent claude-code
npx skills add amElnagdy/guard-skills --skill '*' --agent cursor

A global install is available with --global. Once installed, the usage pattern is a prompt, not a command. The README shows these as plain text invocations inside 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.

What you should see is the agent re-reading the diff under the guard's rules and reporting findings. The README describes the expected outcome for test-guard as a generated test file coming back as "do not merge" with rule-by-rule fixes. For wp-guard it describes a generated plugin that stops echoing raw request data and gives a writing REST route a real permission callback. Those are the project's own descriptions of behaviour, not measured results.

Updating skills, because installs are copies

The README is explicit that skills install as a copy. A new version in the repository does not reach your agent until you update, which means an installed guard can silently fall behind the rules it is supposed to enforce. Refresh commands are given for all skills and for a single one:

npx skills update                 # all installed skills (alias: upgrade)
npx skills update clean-code-guard

The README notes that --global applies to global installs and --project to project installs, and that re-running npx skills add amElnagdy/guard-skills also re-fetches the latest. This is the main ongoing cost of the project: not configuration, but remembering that the copy on disk is a snapshot. The README does not document rollback to a previous skill version, so if an update changes behaviour you disagree with, the documented path back is not stated.

Where guard-skills is the wrong tool

The README draws its own boundary: "This is not a full process framework and not a broad platform catalog." It contrasts itself with WordPress/agent-skills, which it says teaches agents how to build across the WordPress ecosystem, while guard-skills is narrower and gives agents review gates to run after they have produced work.

That narrowness has consequences. A guard is a prompt-level review, so it depends on the model actually following the skill's rules. Nothing in the README describes a deterministic check, a CI hook, or a failing exit code. If you need a build to break when a query is unprepared, a skill is not a substitute for a static analyzer or a test suite.

The coverage is also uneven by design. clean-code-guard, test-guard and docs-guard are language-agnostic. wp-guard and woo-guard are not: they assume WordPress and WooCommerce conventions, and a Laravel or Rails developer gets nothing from them. The README's own pairing table implies that for most projects you will run one or two guards, not all five, which makes the full-package install more of a convenience than a recommendation.

Finally, the guards review a diff. If your agent produced a large uncommitted change set, the README does not describe how the guard scopes what it reviews.

How it compares to WordPress/agent-skills

The obvious alternative named in the README is WordPress/agent-skills. The difference is one of phase and breadth. WordPress/agent-skills teaches an agent how to build across the WordPress ecosystem, which means it shapes the work as it happens and covers a wider surface of the platform. guard-skills gives the agent review gates to run after the work exists, and its WordPress coverage is split into two guards with distinct responsibilities: wp-guard for the WordPress layer and woo-guard for the WooCommerce layer above it.

If your problem is that the agent does not know how to structure a plugin, the broader teaching set is the better fit. If your problem is that the plugin it wrote echoes raw request data and bypasses HPOS, the guard is the better fit, and the README's own framing supports that reading. The two are not mutually exclusive, and the pairing table inside guard-skills already assumes you will combine guards when a change touches more than one surface.

Maintenance, licence and what to check before adopting

The repository is not archived, and the last push was on 2026-07-04. The README does not publish a release history, and no releases were retrieved, so versioning is not visible from the outside. Updates arrive through the Skills CLI rather than a package registry, which means your upgrade path is the update command documented above and nothing more structured.

The licence is MIT. That permits commercial use, modification and redistribution with the licence and copyright notice retained. It also means no warranty, so the guards are provided as-is. This is a description of the licence text, not legal advice; if your organisation has rules about vendored prompts or agent instructions, route the LICENSE file through whoever reviews third-party material.

The practical pre-adoption checks are small. Run the --list command to confirm the five guards and their names. Confirm which agent you are targeting, since the README's examples name codex, claude-code and cursor and describe the rest as other supported agents via the Skills CLI. Decide whether the WordPress and WooCommerce guards apply to you at all, because for many teams the install is three skills, not five.

Editorial conclusion

Adopt guard-skills if you already run Claude Code, Codex, Cursor or another Skills CLI agent and your main pain is unreviewed AI output rather than agent orchestration. Skip it if you need a full process framework or broad platform coverage; the README says plainly this is not that. Before installing, run the --list command to confirm the five guards and check which agent targets your setup supports, then decide whether you want the whole package or a single guard such as clean-code-guard.

Frequently asked questions

Official sources

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