How zebbern/claude-code-guide works
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 Skills · README.md README · accessibility_tester.agent.md Agent profiles · sync-release-notes.yml Sync notes
Components 20
Docs & contract
Root documentation that explains how Claude Code consumes the repository's content and configuration surfaces.
Agent library
Role-specific subagent prompts and policies for delegated work inside Claude Code.
- Agents guide · Overview of the agent directory and how subagents are organized.
agents/README.md - Agent profiles · 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 · Top-level capability packs used by Claude Code as on-demand instruction bundles.
skills - Skill manifests · Primary skill instructions defined by SKILL.md files across the library.
skills/academic-paper-reviewer/SKILL.md - Skill refs · Reference notes, rules, examples, and templates that extend skill manifests.
skills/react-best-practices/README.md - Skill rules · Rule packs that encode reusable best-practice guidance for selected skills.
skills/react-best-practices/rules - Skill scripts · Embedded scripts and package tooling inside selected skills for analysis, generation, and validation tasks.
skills/code-to-diagram/scripts - r2-upload · A self-contained TypeScript skill package with CLI-style tooling and onboarding docs.
skills/r2-upload - Playwright · Large multi-part skill set covering Playwright core usage, CLI workflows, CI, migration, and POM patterns.
skills/playwright - Security skills · Skills focused on penetration testing, vuln review, and secure-code workflows.
skills/sql-injection-testing/SKILL.md - Analysis skills · 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 · Overview for the archived prompt collections.
archive/readme.md - Legacy prompts · Older CLAUDE prompt sets retained as reference material.
archive/CLAUDE-s.md - Archived sets · 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 · Workflow that keeps release notes synchronized with changelog and release history.
.github/workflows/sync-release-notes.yml - GitHub Actions · Repository automation boundary that executes maintenance workflows.
.github/workflows
Other components
- License · Repository license file.
LICENSE - Claude Code · External CLI/runtime that loads the repo's prompts, skills, and guidance at session start.
Connections 20
- 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.