# amelnagdy/guard-skills architecture

> Architecture diagram of the GitHub repository amelnagdy/guard-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amelnagdy/guard-skills
- Repository: https://github.com/amelnagdy/guard-skills

## Overview

1. This repository is a **content-first skills package** for coding agents, not an application runtime. Its architecture is centered on a small set of reusable “guard” skills that act as **second-pass review gates** over agent-generated work.

2. The root package is defined by `README.md`, `LICENSE`, `skills.sh.json`, and the `skills/` directory. The README explains the public contract: install the package with the Skills CLI, then invoke a specific guard on a diff or task output before merge or release.

3. The main functional subsystems are the five skill bundles:
   - `clean-code-guard`
   - `test-guard`
   - `docs-guard`
   - `wp-guard`
   - `woo-guard`
   
   Each bundle targets a different failure domain: general code quality, test quality, documentation accuracy, WordPress-specific safety, and WooCommerce-specific correctness.

4. Each skill follows the same internal shape, which is the key architectural pattern in the repo:
   - `SKILL.md` as the entry point and short operating contract
   - `agents/openai.yaml` as agent metadata
   - `references/` as deeper, topic-specific guidance loaded only when needed
   
   This creates a **progressive disclosure** model: the top-level skill stays lightweight, while detailed rules live in references.

5. The primary data flow is **agent output → guard review → corrective feedback**. The repo is designed for reactive use: an external coding agent produces code, tests, or docs; the chosen guard is then applied to the produced diff; the guard returns review findings before the changes are shipped.

6. The boundary between packages is semantic, not technical. `clean-code-guard` is cross-cutting and language-agnostic, while the other four are domain-specialized overlays. `woo-guard` explicitly builds on WordPress concerns and extends them into WooCommerce/H POS/order and money-handling rules.

7. The reference files are the repository’s knowledge base. They encode the review heuristics, checklists, and source citations that make each guard useful. For example, `docs-guard` includes verification-oriented references, while `wp-guard` and `woo-guard` contain security, i18n, checkout, and compatibility guidance.

8. There is **no executable product code**, no server, no build pipeline, and no runtime infrastructure in this repo. Its implementation surface is entirely static content: Markdown guidance plus lightweight YAML agent descriptors. That means the architecture diagram should emphasize **package composition and review workflow**, not application deployment.

9. The repo is intended to be consumed through the **Skills CLI** and supported agents such as Claude Code, Codex, Cursor, and OpenCode. The README shows installation modes at package, single-skill, agent-specific, and global scope, which indicates that distribution is externalized through the CLI rather than bundled tooling in this repo.

10. External service usage is minimal and limited to the package ecosystem. The README links to `skills.sh` for installation and package discovery, but the repository itself does not depend on network services, APIs, or credentials at runtime. That keeps the trust boundary simple: content is inspectable and self-contained.

11. The repo’s validation posture is also part of the architecture. The README describes maintainers using `skillspector` and local validation before publishing, reinforcing that correctness is enforced by repository inspection and metadata validation, not by executable tests inside the repo.

12. For diagramming purposes, the most accurate mental model is:
   - a root package shell
   - five independently installable guard modules
   - each module containing a small entrypoint, agent metadata, and reference corpus
   - an external agent/CLI consumer that loads the right skill and applies it to code, tests, or docs before release

13. In short, this repository is a **modular rule-pack library for AI code review**, optimized for small entrypoints, deferred detail loading, and clear domain separation. Its main architectural concern is not data processing but **how quality checks are packaged, selected, and applied** across different kinds of generated work.

Main entry points: [`skills`](https://github.com/amelnagdy/guard-skills/tree/master/skills) (Skills dir), [`skills/clean-code-guard/SKILL.md`](https://github.com/amelnagdy/guard-skills/blob/master/skills/clean-code-guard/SKILL.md) (Clean code), [`skills/docs-guard/SKILL.md`](https://github.com/amelnagdy/guard-skills/blob/master/skills/docs-guard/SKILL.md) (Docs guard), [`skills/wp-guard/SKILL.md`](https://github.com/amelnagdy/guard-skills/blob/master/skills/wp-guard/SKILL.md) (WP guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Root package"]
  node_readme["README<br/>contract<br/>[README.md]"]
  node_license["License"]
  node_skills_manifest["Skills manifest<br/>distribution metadata<br/>[skills.sh.json]"]
  node_skills_dir["Skills dir<br/>skill packages"]
end

subgraph group_external["External consumers"]
  node_skills_cli["Skills CLI<br/>installer/runtime"]
  node_ai_agents["Coding agents<br/>external agents"]
  node_skillspector["Skillspector<br/>validation tool"]
end

subgraph group_clean["Clean code guard"]
  node_clean_skill["Clean code<br/>guard bundle<br/>[SKILL.md]"]
  node_clean_agents["Agent meta<br/>agent config<br/>[openai.yaml]"]
  node_clean_refs[("Guidance<br/>reference corpus")]
end

subgraph group_test["Test guard"]
  node_test_skill["Test guard<br/>guard bundle<br/>[SKILL.md]"]
  node_test_agents["Agent meta<br/>agent config<br/>[openai.yaml]"]
  node_test_refs[("Guidance<br/>reference corpus")]
end

subgraph group_docs["Docs guard"]
  node_docs_skill["Docs guard<br/>guard bundle<br/>[SKILL.md]"]
  node_docs_agents["Agent meta<br/>agent config<br/>[openai.yaml]"]
  node_docs_refs[("Guidance<br/>reference corpus")]
end

subgraph group_wp["WordPress guard"]
  node_wp_skill["WP guard<br/>guard bundle<br/>[SKILL.md]"]
  node_wp_agents["Agent meta<br/>agent config<br/>[openai.yaml]"]
  node_wp_refs[("Guidance<br/>reference corpus")]
end

subgraph group_woo["WooCommerce guard"]
  node_woo_skill["Woo guard<br/>guard bundle<br/>[SKILL.md]"]
  node_woo_agents["Agent meta<br/>agent config<br/>[openai.yaml]"]
  node_woo_refs[("Guidance<br/>reference corpus")]
end

node_skills_cli -->|"discovers"| node_skills_manifest
node_skills_cli -->|"loads"| node_skills_dir
node_ai_agents -->|"invoke"| node_skills_cli
node_skillspector -->|"validates"| node_skills_manifest
node_readme -->|"documents"| node_skills_cli
node_skills_dir -->|"contains"| node_clean_skill
node_skills_dir -->|"contains"| node_test_skill
node_skills_dir -->|"contains"| node_docs_skill
node_skills_dir -->|"contains"| node_wp_skill
node_skills_dir -->|"contains"| node_woo_skill
node_clean_skill -->|"uses"| node_clean_agents
node_clean_skill -->|"expands to"| node_clean_refs
node_test_skill -->|"uses"| node_test_agents
node_test_skill -->|"expands to"| node_test_refs
node_docs_skill -->|"uses"| node_docs_agents
node_docs_skill -->|"expands to"| node_docs_refs
node_wp_skill -->|"uses"| node_wp_agents
node_wp_skill -->|"expands to"| node_wp_refs
node_woo_skill -->|"uses"| node_woo_agents
node_woo_skill -->|"expands to"| node_woo_refs
node_clean_skill -.->|"parallel"| node_test_skill
node_clean_skill -.->|"parallel"| node_docs_skill
node_clean_skill -.->|"overlay"| node_wp_skill
node_wp_skill -.->|"specializes"| node_woo_skill
node_docs_skill -.->|"matches"| node_readme

click node_readme "https://github.com/amelnagdy/guard-skills/blob/master/README.md"
click node_license "https://github.com/amelnagdy/guard-skills/tree/master/LICENSE"
click node_skills_manifest "https://github.com/amelnagdy/guard-skills/blob/master/skills.sh.json"
click node_skills_dir "https://github.com/amelnagdy/guard-skills/tree/master/skills"
click node_clean_skill "https://github.com/amelnagdy/guard-skills/blob/master/skills/clean-code-guard/SKILL.md"
click node_clean_agents "https://github.com/amelnagdy/guard-skills/blob/master/skills/clean-code-guard/agents/openai.yaml"
click node_clean_refs "https://github.com/amelnagdy/guard-skills/tree/master/skills/clean-code-guard/references"
click node_test_skill "https://github.com/amelnagdy/guard-skills/blob/master/skills/test-guard/SKILL.md"
click node_test_agents "https://github.com/amelnagdy/guard-skills/blob/master/skills/test-guard/agents/openai.yaml"
click node_test_refs "https://github.com/amelnagdy/guard-skills/tree/master/skills/test-guard/references"
click node_docs_skill "https://github.com/amelnagdy/guard-skills/blob/master/skills/docs-guard/SKILL.md"
click node_docs_agents "https://github.com/amelnagdy/guard-skills/blob/master/skills/docs-guard/agents/openai.yaml"
click node_docs_refs "https://github.com/amelnagdy/guard-skills/tree/master/skills/docs-guard/references"
click node_wp_skill "https://github.com/amelnagdy/guard-skills/blob/master/skills/wp-guard/SKILL.md"
click node_wp_agents "https://github.com/amelnagdy/guard-skills/blob/master/skills/wp-guard/agents/openai.yaml"
click node_wp_refs "https://github.com/amelnagdy/guard-skills/tree/master/skills/wp-guard/references"
click node_woo_skill "https://github.com/amelnagdy/guard-skills/blob/master/skills/woo-guard/SKILL.md"
click node_woo_agents "https://github.com/amelnagdy/guard-skills/blob/master/skills/woo-guard/agents/openai.yaml"
click node_woo_refs "https://github.com/amelnagdy/guard-skills/tree/master/skills/woo-guard/references"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_license,node_skills_manifest,node_skills_dir,node_woo_skill,node_woo_agents,node_woo_refs toneBlue
class node_skills_cli,node_ai_agents,node_skillspector toneAmber
class node_clean_skill,node_clean_agents,node_clean_refs toneMint
class node_test_skill,node_test_agents,node_test_refs toneRose
class node_docs_skill,node_docs_agents,node_docs_refs toneIndigo
class node_wp_skill,node_wp_agents,node_wp_refs toneTeal
```

## Components

### Root package

Repository shell and distribution metadata.

- [README](https://github.com/amelnagdy/guard-skills/blob/master/README.md): contract · Public install and invocation contract for the skill package. · `README.md`
- [License](https://github.com/amelnagdy/guard-skills/tree/master/LICENSE): license · Repository licensing terms. · `LICENSE`
- [Skills manifest](https://github.com/amelnagdy/guard-skills/blob/master/skills.sh.json): distribution metadata · Package metadata used by Skills CLI discovery and installation. · `skills.sh.json`
- [Skills dir](https://github.com/amelnagdy/guard-skills/tree/master/skills): skill packages · Container for the modular guard bundles. · `skills`

### External consumers

Tools and agents that install or invoke guards from outside the repo.

- **Skills CLI**: installer/runtime · External consumer that installs and resolves skills from the package.
- **Coding agents**: external agents · Claude Code, Codex, Cursor, OpenCode, and similar consumers.
- **Skillspector**: validation tool · Local validation used by maintainers before publishing.

### Clean code guard

Cross-cutting guard for general code quality.

- [Clean code](https://github.com/amelnagdy/guard-skills/blob/master/skills/clean-code-guard/SKILL.md): guard bundle · Entry skill for general code-quality review. · `skills/clean-code-guard/SKILL.md`
- [Agent meta](https://github.com/amelnagdy/guard-skills/blob/master/skills/clean-code-guard/agents/openai.yaml): agent config · OpenAI-oriented agent metadata for the clean-code guard. · `skills/clean-code-guard/agents/openai.yaml`
- [Guidance](https://github.com/amelnagdy/guard-skills/tree/master/skills/clean-code-guard/references): reference corpus · Heuristics and review notes for clean-code decisions. · `skills/clean-code-guard/references`

### Test guard

Guard for test quality across runtimes.

- [Test guard](https://github.com/amelnagdy/guard-skills/blob/master/skills/test-guard/SKILL.md): guard bundle · Entry skill for test quality review. · `skills/test-guard/SKILL.md`
- [Agent meta](https://github.com/amelnagdy/guard-skills/blob/master/skills/test-guard/agents/openai.yaml): agent config · OpenAI-oriented agent metadata for the test guard. · `skills/test-guard/agents/openai.yaml`
- [Guidance](https://github.com/amelnagdy/guard-skills/tree/master/skills/test-guard/references): reference corpus · Framework-specific testing guidance and review notes. · `skills/test-guard/references`

### Docs guard

Guard for documentation accuracy and verification.

- [Docs guard](https://github.com/amelnagdy/guard-skills/blob/master/skills/docs-guard/SKILL.md): guard bundle · Entry skill for documentation review. · `skills/docs-guard/SKILL.md`
- [Agent meta](https://github.com/amelnagdy/guard-skills/blob/master/skills/docs-guard/agents/openai.yaml): agent config · OpenAI-oriented agent metadata for the docs guard. · `skills/docs-guard/agents/openai.yaml`
- [Guidance](https://github.com/amelnagdy/guard-skills/tree/master/skills/docs-guard/references): reference corpus · Verification, docstring, and example guidance for docs review. · `skills/docs-guard/references`

### WordPress guard

Guard for WordPress-specific safety and conventions.

- [WP guard](https://github.com/amelnagdy/guard-skills/blob/master/skills/wp-guard/SKILL.md): guard bundle · Entry skill for WordPress-specific review. · `skills/wp-guard/SKILL.md`
- [Agent meta](https://github.com/amelnagdy/guard-skills/blob/master/skills/wp-guard/agents/openai.yaml): agent config · OpenAI-oriented agent metadata for the WordPress guard. · `skills/wp-guard/agents/openai.yaml`
- [Guidance](https://github.com/amelnagdy/guard-skills/tree/master/skills/wp-guard/references): reference corpus · Security, i18n, and performance guidance for WordPress review. · `skills/wp-guard/references`

### WooCommerce guard

Guard for WooCommerce-specific correctness and commerce rules.

- [Woo guard](https://github.com/amelnagdy/guard-skills/blob/master/skills/woo-guard/SKILL.md): guard bundle · Entry skill for WooCommerce-specific review. · `skills/woo-guard/SKILL.md`
- [Agent meta](https://github.com/amelnagdy/guard-skills/blob/master/skills/woo-guard/agents/openai.yaml): agent config · OpenAI-oriented agent metadata for the WooCommerce guard. · `skills/woo-guard/agents/openai.yaml`
- [Guidance](https://github.com/amelnagdy/guard-skills/tree/master/skills/woo-guard/references): reference corpus · Checkout, money handling, and HPOS/CRUD guidance for WooCommerce review. · `skills/woo-guard/references`

## Connections

- Skills CLI → Skills manifest: discovers · CLI reads package metadata to install or resolve guards.
- Skills CLI → Skills dir: loads · CLI installs the selected skill bundle from the package.
- Coding agents → Skills CLI: invoke · External agents call into the CLI or its installed skills.
- Skillspector → Skills manifest: validates · Maintainers validate package metadata before publishing.
- README → Skills CLI: documents · README describes installation and invocation patterns.
- Skills dir → Clean code: contains · Root skills directory contains the clean-code guard bundle.
- Skills dir → Test guard: contains · Root skills directory contains the test guard bundle.
- Skills dir → Docs guard: contains · Root skills directory contains the docs guard bundle.
- Skills dir → WP guard: contains · Root skills directory contains the WordPress guard bundle.
- Skills dir → Woo guard: contains · Root skills directory contains the WooCommerce guard bundle.
- Clean code → Agent meta: uses · Skill entrypoint is paired with agent metadata.
- Clean code → Guidance: expands to · Deeper review rules live in references.
- Test guard → Agent meta: uses · Skill entrypoint is paired with agent metadata.
- Test guard → Guidance: expands to · Deeper review rules live in references.
- Docs guard → Agent meta: uses · Skill entrypoint is paired with agent metadata.
- Docs guard → Guidance: expands to · Deeper review rules live in references.
- WP guard → Agent meta: uses · Skill entrypoint is paired with agent metadata.
- WP guard → Guidance: expands to · Deeper review rules live in references.
- Woo guard → Agent meta: uses · Skill entrypoint is paired with agent metadata.
- Woo guard → Guidance: expands to · Deeper review rules live in references.
- Clean code → Test guard: parallel · Both are quality-review gates for generated work.
- Clean code → Docs guard: parallel · Both are quality-review gates for generated work.
- Clean code → WP guard: overlay · WordPress rules extend the general guard model.
- WP guard → Woo guard: specializes · WooCommerce guard builds on WordPress concerns.
- Docs guard → README: matches · Docs guard reinforces documentation and verification contracts.