# zebbern/claude-code-guide architecture

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

- Interactive diagram: https://gitdiagram.com/zebbern/claude-code-guide
- Repository: https://github.com/zebbern/claude-code-guide

## Overview

1. **What this repo is**
   - This is not a product application; it is a **content-and-configuration repository for Claude Code**.
   - Its main job is to package reusable guidance for the Claude Code CLI: agent prompts, skills, archived templates, and documentation about how the Claude Code ecosystem is organized.

2. **Top-level architecture**
   - The repository is centered around three content domains:
     - **`agents/`**: subagent definitions
     - **`skills/`**: modular capability packs / slash-command-like instructions
     - **`archive/`**: legacy and historical prompt libraries
   - Supporting the content are the root docs: **`README.md`**, **`CHANGELOG.md`**, and a small **GitHub Actions** workflow under `.github/workflows/`.

3. **Primary runtime boundary**
   - The actual runtime is **Claude Code itself**, external to this repo.
   - This repo supplies files that Claude Code loads or references at session start, such as project memory, rules, agents, and skills.
   - In other words, the repo is a **knowledge and policy layer**, not the execution engine.

4. **Agent subsystem**
   - `agents/*.agent.md` contains many role-specific agent profiles: frontend, backend, security, DevOps, testing, language specialists, and orchestration roles.
   - These are meant to be **discrete prompts + tool policies** for Claude Code subagents.
   - The architecture implication is a **role-based delegation model**: the main assistant can hand specialized work to a narrower agent instead of using one monolithic prompt.

5. **Skills subsystem**
   - `skills/*/SKILL.md` is the largest functional surface.
   - Each skill is a self-contained instruction bundle, often with:
     - a `SKILL.md` manifest/instructions
     - optional supporting docs, references, or templates
     - optional executable scripts
   - This creates a **plug-in style capability layer** where Claude Code can load a skill on demand or via a slash command.

6. **Executable skill packages**
   - Some skills are not just text; they include real tooling:
     - Python scripts for analysis/generation tasks
     - Node/TypeScript packages for tasks like `r2-upload`
     - supporting assets, templates, schemas, and examples
   - These are the only parts of the repo that behave like runnable utilities, but they are **isolated per skill** rather than forming a shared application codebase.

7. **Archive subsystem**
   - `archive/` holds older generations of prompts and role definitions, grouped by domain such as Python, Django, React, Rails, security, testing, and orchestrators.
   - This acts as a **deprecated/reference library** rather than active source of truth.
   - Architecturally, it is a boundary for backward compatibility and historical reuse.

8. **Documentation and guidance layer**
   - The root `README.md` is effectively the repo’s architecture manual.
   - It explains how Claude Code consumes:
     - environment variables
     - config files
     - memory files
     - rules directories
     - MCP servers
     - hooks
     - plugins
   - So the documentation is not ancillary; it is the **primary integration contract** for the rest of the repository.

9. **Automation boundary**
   - `.github/workflows/sync-release-notes.yml` indicates a small CI automation layer.
   - `CHANGELOG.md` is the source of release history, and the workflow likely keeps release notes synchronized with upstream releases.
   - This is the repo’s only obvious continuous automation path, and it is focused on **documentation/release hygiene**, not product deployment.

10. **How information flows through the repo**
   - Human authors edit docs, agent prompts, and skill packs.
   - Claude Code loads those files as context or tool definitions.
   - Claude Code may delegate work to a specialized agent, invoke a skill, or call an embedded helper script.
   - Changes to release history propagate through GitHub Actions into synchronized release notes.

11. **External integration points**
   - The README describes integration boundaries with:
     - **Claude Code CLI/runtime**
     - **Model Context Protocol (MCP)** servers
     - **hooks**
     - **plugins**
     - **GitHub Actions**
   - These are important because the repo mostly defines the **configuration surface** for those integrations rather than implementing the integrations directly.

12. **Practical diagram takeaway**
   - If you draw this repo, model it as a **content hub with extension points**, not as an app backend/frontend split.
   - The main boxes are:
     - documentation
     - agent library
     - skill library
     - archived references
     - CI/release-note sync
   - The main arrows go outward to Claude Code, which consumes these assets at runtime.

Main entry points: [`skills`](https://github.com/zebbern/claude-code-guide/tree/main/skills) (Skills), [`README.md`](https://github.com/zebbern/claude-code-guide/blob/main/README.md) (README), [`agents/accessibility_tester.agent.md`](https://github.com/zebbern/claude-code-guide/blob/main/agents/accessibility_tester.agent.md) (Agent profiles), [`.github/workflows/sync-release-notes.yml`](https://github.com/zebbern/claude-code-guide/blob/main/.github/workflows/sync-release-notes.yml) (Sync notes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs & contract"]
  node_readme["README<br/>architecture guide<br/>[README.md]"]
  node_changelog["CHANGELOG<br/>release history<br/>[CHANGELOG.md]"]
end

subgraph group_agents["Agent library"]
  node_agents_readme["Agents guide<br/>agent index<br/>[README.md]"]
  node_agent_profiles["Agent profiles<br/>role prompts"]
end

subgraph group_skills["Skill library"]
  node_skills_root["Skills<br/>skill library"]
  node_skill_manifests["Skill manifests<br/>skill entries<br/>[SKILL.md]"]
  node_skill_refs["Skill refs<br/>supporting docs<br/>[README.md]"]
  node_skill_rules["Skill rules<br/>policy rules"]
  node_skill_scripts["Skill scripts<br/>runnable helpers"]
  node_skill_r2_upload["r2-upload<br/>typescript skill"]
  node_skill_playwright["Playwright<br/>test skill suite"]
  node_skill_security["Security skills<br/>security pack<br/>[SKILL.md]"]
  node_skill_analysis["Analysis skills<br/>analysis pack<br/>[SKILL.md]"]
end

subgraph group_archive["Archive"]
  node_archive_readme["Archive guide<br/>archive index<br/>[readme.md]"]
  node_archive_legacy["Legacy prompts<br/>historical prompts<br/>[CLAUDE-s.md]"]
  node_archive_collections["Archived sets<br/>domain archives"]
end

subgraph group_automation["Automation"]
  node_workflow_sync["Sync notes<br/>github action"]
  node_github_actions(("GitHub Actions<br/>ci platform<br/>[workflows]"))
end

node_license["License<br/>legal"]
node_claude_code(("Claude Code<br/>external runtime"))

node_readme -->|"documents contract"| node_claude_code
node_agents_readme -->|"organizes"| node_agent_profiles
node_claude_code -->|"delegates to"| node_agent_profiles
node_claude_code -->|"loads skills"| node_skills_root
node_skills_root -->|"contains"| node_skill_manifests
node_skills_root -->|"extends with"| node_skill_refs
node_skills_root -->|"encodes"| node_skill_rules
node_skills_root -->|"invokes helpers"| node_skill_scripts
node_skills_root -->|"includes"| node_skill_r2_upload
node_skills_root -->|"includes"| node_skill_playwright
node_skills_root -->|"includes"| node_skill_security
node_skills_root -->|"includes"| node_skill_analysis
node_archive_readme -->|"indexes"| node_archive_collections
node_claude_code -.->|"may reference"| node_archive_collections
node_changelog -->|"drives"| node_workflow_sync
node_workflow_sync -->|"runs on"| node_github_actions
node_github_actions -.->|"supports hygiene"| node_readme
node_license -.->|"bounds repo"| node_readme
node_skills_root -.->|"extends runtime"| node_claude_code
node_agent_profiles -.->|"complements"| node_skills_root

click node_readme "https://github.com/zebbern/claude-code-guide/blob/main/README.md"
click node_changelog "https://github.com/zebbern/claude-code-guide/blob/main/CHANGELOG.md"
click node_license "https://github.com/zebbern/claude-code-guide/tree/main/LICENSE"
click node_agents_readme "https://github.com/zebbern/claude-code-guide/blob/main/agents/README.md"
click node_agent_profiles "https://github.com/zebbern/claude-code-guide/blob/main/agents/accessibility_tester.agent.md"
click node_skills_root "https://github.com/zebbern/claude-code-guide/tree/main/skills"
click node_skill_manifests "https://github.com/zebbern/claude-code-guide/blob/main/skills/academic-paper-reviewer/SKILL.md"
click node_skill_refs "https://github.com/zebbern/claude-code-guide/blob/main/skills/react-best-practices/README.md"
click node_skill_rules "https://github.com/zebbern/claude-code-guide/tree/main/skills/react-best-practices/rules"
click node_skill_scripts "https://github.com/zebbern/claude-code-guide/tree/main/skills/code-to-diagram/scripts"
click node_skill_r2_upload "https://github.com/zebbern/claude-code-guide/tree/main/skills/r2-upload"
click node_skill_playwright "https://github.com/zebbern/claude-code-guide/tree/main/skills/playwright"
click node_skill_security "https://github.com/zebbern/claude-code-guide/blob/main/skills/sql-injection-testing/SKILL.md"
click node_skill_analysis "https://github.com/zebbern/claude-code-guide/blob/main/skills/repo-audit/SKILL.md"
click node_archive_readme "https://github.com/zebbern/claude-code-guide/blob/main/archive/readme.md"
click node_archive_legacy "https://github.com/zebbern/claude-code-guide/blob/main/archive/CLAUDE-s.md"
click node_archive_collections "https://github.com/zebbern/claude-code-guide/tree/main/archive/collection"
click node_workflow_sync "https://github.com/zebbern/claude-code-guide/blob/main/.github/workflows/sync-release-notes.yml"
click node_github_actions "https://github.com/zebbern/claude-code-guide/blob/main/.github/workflows"

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_changelog toneBlue
class node_agents_readme,node_agent_profiles toneAmber
class node_skills_root,node_skill_manifests,node_skill_refs,node_skill_rules,node_skill_scripts,node_skill_r2_upload,node_skill_playwright,node_skill_security,node_skill_analysis toneMint
class node_archive_readme,node_archive_legacy,node_archive_collections toneRose
class node_workflow_sync,node_github_actions toneIndigo
class node_license,node_claude_code toneNeutral
```

## Components

### Docs & contract

Root documentation that explains how Claude Code consumes the repository's content and configuration surfaces.

- [README](https://github.com/zebbern/claude-code-guide/blob/main/README.md): architecture guide · Primary integration manual for Claude Code, covering memory, rules, hooks, MCP, plugins, and runtime boundaries. · `README.md`
- [CHANGELOG](https://github.com/zebbern/claude-code-guide/blob/main/CHANGELOG.md): release history · Record of repository changes that feeds release-note synchronization. · `CHANGELOG.md`

### Agent library

Role-specific subagent prompts and policies for delegated work inside Claude Code.

- [Agents guide](https://github.com/zebbern/claude-code-guide/blob/main/agents/README.md): agent index · Overview of the agent directory and how subagents are organized. · `agents/README.md`
- [Agent profiles](https://github.com/zebbern/claude-code-guide/blob/main/agents/accessibility_tester.agent.md): role prompts · Collection of role-specific subagent definitions for specialization and delegation. · `agents/accessibility_tester.agent.md`

### Skill library

Modular capability packs with manifests, references, rules, and embedded helpers.

- [Skills](https://github.com/zebbern/claude-code-guide/tree/main/skills): skill library · Top-level capability packs used by Claude Code as on-demand instruction bundles. · `skills`
- [Skill manifests](https://github.com/zebbern/claude-code-guide/blob/main/skills/academic-paper-reviewer/SKILL.md): skill entries · Primary skill instructions defined by SKILL.md files across the library. · `skills/academic-paper-reviewer/SKILL.md`
- [Skill refs](https://github.com/zebbern/claude-code-guide/blob/main/skills/react-best-practices/README.md): supporting docs · Reference notes, rules, examples, and templates that extend skill manifests. · `skills/react-best-practices/README.md`
- [Skill rules](https://github.com/zebbern/claude-code-guide/tree/main/skills/react-best-practices/rules): policy rules · Rule packs that encode reusable best-practice guidance for selected skills. · `skills/react-best-practices/rules`
- [Skill scripts](https://github.com/zebbern/claude-code-guide/tree/main/skills/code-to-diagram/scripts): runnable helpers · Embedded scripts and package tooling inside selected skills for analysis, generation, and validation tasks. · `skills/code-to-diagram/scripts`
- [r2-upload](https://github.com/zebbern/claude-code-guide/tree/main/skills/r2-upload): typescript skill · A self-contained TypeScript skill package with CLI-style tooling and onboarding docs. · `skills/r2-upload`
- [Playwright](https://github.com/zebbern/claude-code-guide/tree/main/skills/playwright): test skill suite · Large multi-part skill set covering Playwright core usage, CLI workflows, CI, migration, and POM patterns. · `skills/playwright`
- [Security skills](https://github.com/zebbern/claude-code-guide/blob/main/skills/sql-injection-testing/SKILL.md): security pack · Skills focused on penetration testing, vuln review, and secure-code workflows. · `skills/sql-injection-testing/SKILL.md`
- [Analysis skills](https://github.com/zebbern/claude-code-guide/blob/main/skills/repo-audit/SKILL.md): analysis pack · Skills for auditing, documentation, data analysis, and other inspection-oriented tasks. · `skills/repo-audit/SKILL.md`

### Archive

Historical prompt libraries and deprecated role definitions kept for reference.

- [Archive guide](https://github.com/zebbern/claude-code-guide/blob/main/archive/readme.md): archive index · Overview for the archived prompt collections. · `archive/readme.md`
- [Legacy prompts](https://github.com/zebbern/claude-code-guide/blob/main/archive/CLAUDE-s.md): historical prompts · Older CLAUDE prompt sets retained as reference material. · `archive/CLAUDE-s.md`
- [Archived sets](https://github.com/zebbern/claude-code-guide/tree/main/archive/collection): domain archives · Domain-based archived prompt collections for Python, Django, React, Rails, security, testing, and related areas. · `archive/collection`

### Automation

Small repository automation focused on release-note synchronization.

- [Sync notes](https://github.com/zebbern/claude-code-guide/blob/main/.github/workflows/sync-release-notes.yml): github action · Workflow that keeps release notes synchronized with changelog and release history. · `.github/workflows/sync-release-notes.yml`
- [GitHub Actions](https://github.com/zebbern/claude-code-guide/blob/main/.github/workflows): ci platform · Repository automation boundary that executes maintenance workflows. · `.github/workflows`

### Other components

- [License](https://github.com/zebbern/claude-code-guide/tree/main/LICENSE): legal · Repository license file. · `LICENSE`
- **Claude Code**: external runtime · External CLI/runtime that loads the repo's prompts, skills, and guidance at session start.

## Connections

- README → Claude Code: documents contract · Explains how the external runtime consumes repository content.
- Agents guide → Agent profiles: organizes · The agents index explains the role library.
- Claude Code → Agent profiles: delegates to · Claude Code can hand specialized work to a narrower subagent.
- Claude Code → Skills: loads skills · The runtime loads the skills directory as its capability layer.
- Skills → Skill manifests: contains · Skill manifests provide the main instruction entrypoints.
- Skills → Skill refs: extends with · Supporting docs refine and contextualize individual skills.
- Skills → Skill rules: encodes · Rules files capture reusable policy and best-practice guidance.
- Skills → Skill scripts: invokes helpers · Some skills embed executable helpers for analysis and generation.
- Skills → r2-upload: includes · One skill is a fuller package with TypeScript tooling and docs.
- Skills → Playwright: includes · A major skill suite spans Playwright core, CLI, CI, migration, and POM workflows.
- Skills → Security skills: includes · Several skills focus on security testing, auditing, and offensive methodology.
- Skills → Analysis skills: includes · Other skills focus on auditing, documentation, and analytical workflows.
- Archive guide → Archived sets: indexes · The archive guide points to historical prompt libraries.
- Claude Code → Archived sets: may reference · Archived prompts remain available as legacy reference material.
- CHANGELOG → Sync notes: drives · Release history is synchronized by the workflow.
- Sync notes → GitHub Actions: runs on · The sync workflow is executed by GitHub Actions.
- GitHub Actions → README: supports hygiene · Automation complements the documentation-first repository contract.
- License → README: bounds repo · Legal and documentation roots frame the repository.
- Skills → Claude Code: extends runtime · Skills expand Claude Code's behavior without changing the engine.
- Agent profiles → Skills: complements · Agents and skills form parallel extension surfaces.