amElnagdy/guard-skills: open-source project for self-hosters

Focused guard skills for coding agents: second-pass quality gates that catch the systematic failure modes of AI-generated code, tests, and docs before they ship.

Best use: let your agent do the work, then invoke the relevant guard on the diff before you present, commit, or merge it. These skills can guide writing when you explicitly ask for that, but they are strongest as reactive review passes.

Install

Browse the package first:

npx skills add amElnagdy/guard-skills --list

Install the package:

npx skills add amElnagdy/guard-skills

Or install one guard:

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

Install for a specific agent:

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

Install globally:

npx skills add amElnagdy/guard-skills --global

Works with Claude Code, Codex, Cursor, OpenCode, and other supported agents via the Skills CLI.

How to use them

Run a guard after your agent produces work:

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.
Use $wp-guard on this WordPress plugin change.
Use $woo-guard on this WooCommerce checkout change.

Use a guard up front only when you want that constraint active while writing:

Use $wp-guard while implementing this REST endpoint, then self-check before delivery.

Which guard to run

Guard	Use after the agent changed	Catches	Pair with
`clean-code-guard`	Production code in any language	LLM code smells, over-abstraction, broad error swallowing, bad names, SOLID/DRY/KISS/YAGNI violations	Platform-specific guards
`test-guard`	Test code	Mock abuse, duplicate tests, implementation-detail assertions, tests that catch nothing	`clean-code-guard` when test helpers contain real logic
`docs-guard`	READMEs, docstrings, API docs, changelogs, tutorials	Hallucinated symbols, broken samples, docs-vs-code drift, unverifiable claims	Any guard whose behavior is documented
`wp-guard`	WordPress plugin, theme, block, REST, AJAX, shortcode, query, or WP-CLI code	Escaping, sanitization, nonces, capabilities, prepared queries, i18n, query/caching mistakes	`clean-code-guard`; `woo-guard` when Woo APIs appear
`woo-guard`	WooCommerce extension, checkout, order, product, gateway, shipping, or HPOS code	Direct order meta, HPOS breakage, missing compatibility declarations, checkout bypasses, money errors	`wp-guard` for the WordPress layer

The skills

clean-code-guard

Applies Clean Code, SOLID, DRY/KISS/YAGNI to generated or changed code in any language, plus an AI-specific layer most rule packs miss: catch-all error swallowing, hardcoded "success" returns, hallucinated APIs, premature abstraction, comment pollution, and copy-from-similar bugs.

Why the AI layer matters: the skill references published research on duplication growth, package hallucination, and agents declaring success despite failed tests.

You'll feel it when: your agent refactors without silently changing behavior, asks before changing a contract, justifies what it deliberately left out, and stops wrapping everything in try/catch -> return ok.

test-guard

A quality gate for generated or changed test code in any language: pytest, PHPUnit/Pest, Jest/Vitest, Go tests, WordPress/WooCommerce tests, and more. Nine universal rules catch AI test bloat: mock only at system boundaries, never mock your own state objects, parametrize instead of copy-pasting, delete tests that catch nothing, and treat production regression tests as sacred.

Framework specifics live in progressive-disclosure references the agent loads only when relevant, including a dedicated reference for LLM applications.

You'll feel it when: a generated test file with MagicMock() state, duplicated test bodies, and log-message assertions comes back as "do not merge" with rule-by-rule fixes.

docs-guard

A documentation accuracy gate for READMEs, API references, docstrings, PHPDoc/JSDoc, changelogs, and tutorials. Its core move: treat documentation as a list of claims and verify every one against the codebase.

You'll feel it when: a generated README stops referencing functions that do not exist, @param tags match the real signature, samples run on a clean machine, and "blazingly fast" leaves the building.

wp-guard

A WordPress shipping guard for generated or changed plugins, themes, blocks, REST endpoints, AJAX handlers, shortcodes, WP-CLI commands, and queries. It enforces the layer generic clean-code guidance misses: escaping and sanitization, nonce plus capability checks, prepared database queries, core APIs before custom plumbing, translation-ready strings, and query/caching discipline.

You'll feel it when: a generated plugin stops echoing raw request data, a writing REST route gets a real permission callback, every string ships translation-ready, and a million-row site does not get handed posts_per_page => -1.

woo-guard

A WooCommerce shipping guard for generated or changed extensions, payment and shipping integrations, checkout customizations, and order/product logic. It sits on top of wp-guard and enforces what is WooCommerce-specific: HPOS-safe order access, CRUD over direct meta, truthful feature-compatibility declarations, server-side checkout validation, money-handling discipline, and hooks over template overrides.

You'll feel it when: order code survives HPOS, stock updates stop racing, checkout rules hold without JavaScript, and '$' . $amount never reaches a store that sells in dirhams.

How this differs

This is not a full process framework and not a broad platform catalog. Repos like WordPress/agent-skills teach agents how to build across the WordPress ecosystem. guard-skills is narrower: it gives agents review gates to run after they have produced work, so common AI failure modes get caught before the work reaches your repo.

Repository shape

Each skill is a folder with a SKILL.md entrypoint, lightweight agent metadata, and progressive-disclosure references:

skills/
├── clean-code-guard/
│   ├── SKILL.md
���   ├── agents/openai.yaml
│   └── references/
├── docs-guard/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   └── references/
├── test-guard/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   └── references/
├── woo-guard/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   └── references/
└── wp-guard/
    ├── SKILL.md
    ├── agents/openai.yaml
    └── references/

The SKILL.md stays small so it loads cheaply; deeper guidance loads only when the task needs it.

Trust and validation

This package is intentionally inspectable:

Skill content is Markdown plus lightweight agents/openai.yaml metadata.
There are no executable scripts, network calls, MCP server dependencies, or credentials.
External source URLs live in each skill's references/sources.md.

Maintainer checks before publishing:

npx skills add . --list --full-depth

With SkillSpector installed:

for skill in skills/*; do
  skillspector scan "$skill" --no-llm
done

When authoring with a local skill-creator validator, each skill is also checked with quick_validate.py before release.