# alirezarezvani/claude-code-skill-factory architecture

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

- Interactive diagram: https://gitdiagram.com/alirezarezvani/claude-code-skill-factory
- Repository: https://github.com/alirezarezvani/claude-code-skill-factory

## Overview

#### Purpose and Execution Model
This is a Claude Code ecosystem factory, not a deployable application. It supplies declarative agents, slash commands, reusable skill packages, templates, and examples for creating and installing Claude Skills, Claude Code agents, hooks, prompts, and Codex-compatible guidance. Primary user entry points are Claude Code natural-language agent activation and slash-command definitions in `.claude/`.

Paths: `.claude/agents/factory-guide.md`, `.claude/commands/build.md`, `CLAUDE.md`.

#### Interactive Factory Orchestration
`factory-guide` is the conversational router: it gathers the requested artifact type and delegates to specialist guides for skills, agents, prompts, or hooks. The guides encode the interactive workflow rather than a conventional runtime service.

Paths: `.claude/agents/factory-guide.md`, `.claude/agents/skills-guide.md`, `.claude/agents/hooks-guide.md`.

#### Command-Control Surface
Slash-command Markdown files are the operational interface for build, validation, installation, testing, status, documentation synchronization, Codex execution, and Git/GitHub workflows. Commands coordinate the artifact lifecycle: collect requirements → generate files/package → validate → install or commit.

Paths: `.claude/commands/build.md`, `.claude/commands/validate-output.md`, `.claude/commands/install-skill.md`.

#### Generation Templates and Reference Contract
Factory prompts and reference documents establish output contracts: YAML-frontmatter metadata, expected directory layouts, implementation/sample artifacts, safety requirements, and platform conventions. They are the principal boundary between generic user requirements and generated Claude-compatible artifacts.

Paths: `documentation/templates/SKILLS_FACTORY_PROMPT.md`, `documentation/templates/AGENTS_FACTORY_PROMPT.md`, `documentation/templates/HOOKS_FACTORY_PROMPT.md`.

#### Packaged Skill Implementations
`generated-skills/` contains independently installable, mostly Python-based skill packages. Each package has its own `SKILL.md`, documentation, sample inputs/expected outputs, and specialized pipeline modules; there is no shared application runtime across them. High-value factories include prompt generation, hooks, agents, commands, CLAUDE.md maintenance, and Claude–Codex bridging.

Paths: `generated-skills/prompt-factory/SKILL.md`, `generated-skills/hook-factory/hook_factory.py`, `generated-skills/agent-factory/agent_generator.py`.

#### Automation, Installation, and Safety Boundaries
Generated hook and bridge skills can execute local scripts, modify Claude configuration, invoke formatting/tests, and bridge to Codex CLI. Validation and installer layers are therefore the key control boundary before artifacts reach user/project Claude settings. Some hooks include shell scripts; Python is the dominant implementation language.

Paths: `generated-skills/hook-factory/validator.py`, `generated-skills/hook-factory/installer.py`, `generated-skills/codex-cli-bridge/safety_mechanism.py`.

#### Cross-Tool and GitHub Integration
The Codex bridge translates or derives `AGENTS.md` from Claude guidance and can execute Codex CLI workflows. GitHub Actions provide repository governance and automation—quality gates, security checks, issue/plan conversion, releases, and branch/PR control—using GitHub-hosted workflow infrastructure and GitHub APIs.

Paths: `generated-skills/codex-cli-bridge/bridge.py`, `.github/workflows/ci-quality-gate.yml`, `.github/workflows/plan-to-tasks.yml`.

#### Artifact Outputs and Distribution
Outputs are versioned in-repo as generated agents, commands, hooks, prompts, and skills; many skills also ship ZIP archives for distribution. Consumers copy/install these directories into Claude Code locations, while generated agent and command directories represent ready-to-use declarative extensions.

Paths: `generated-agents/claude-md-guardian/claude-md-guardian.md`, `generated-commands/enhance-claude-md/enhance-claude-md.md`, `generated-hooks/auto-sync-plan-to-github/hook.json`.

Main entry points: [`.claude/commands/build.md`](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/build.md) (Build command), [`.claude/agents/factory-guide.md`](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/factory-guide.md) (Factory guide), [`generated-skills/hook-factory/validator.py`](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/validator.py) (Hook validator), [`generated-skills/hook-factory/installer.py`](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/installer.py) (Hook installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Factory Control"]
  node_claude["Repository guidance<br/>Claude instructions<br/>[CLAUDE.md]"]
  node_factory_guide["Factory guide<br/>conversational router<br/>[factory-guide.md]"]
  node_skills_guide["Skills guide<br/>specialist guide<br/>[skills-guide.md]"]
  node_hooks_guide["Hooks guide<br/>specialist guide<br/>[hooks-guide.md]"]
  node_build_command["Build command<br/>slash command<br/>[build.md]"]
  node_validate_command["Validate output<br/>slash command<br/>[validate-output.md]"]
  node_install_command["Install skill<br/>slash command<br/>[install-skill.md]"]
end

subgraph group_contracts["Generation Contracts"]
  node_skill_template["Skills factory contract<br/>generation template"]
  node_agent_template["Agents factory contract<br/>generation template"]
  node_hook_template["Hooks factory contract<br/>generation template"]
end

subgraph group_packages["Installable Skill Packages"]
  node_prompt_factory["Prompt factory<br/>skill package<br/>[SKILL.md]"]
  node_agent_factory["Agent factory<br/>Python generator<br/>[agent_generator.py]"]
  node_hook_factory["Hook factory<br/>Python package<br/>[hook_factory.py]"]
  node_hook_validator["Hook validator<br/>validation layer<br/>[validator.py]"]
  node_hook_installer["Hook installer<br/>installation layer<br/>[installer.py]"]
end

subgraph group_outputs["Generated Outputs"]
  node_generated_agents["Generated agents<br/>declarative output"]
  node_generated_commands["Generated commands<br/>declarative output"]
  node_generated_hooks["Generated hooks<br/>hook output<br/>[hook.json]"]
end

subgraph group_external["External Automation"]
  node_codex_bridge{{"Codex bridge<br/>cross-tool bridge<br/>[bridge.py]"}}
  node_bridge_safety["Bridge safety<br/>safety layer"]
  node_github_workflows{{"GitHub workflows<br/>GitHub Actions"}}
end

node_claude -->|"guides use of"| node_factory_guide
node_factory_guide -->|"delegates skills"| node_skills_guide
node_factory_guide -->|"delegates hooks"| node_hooks_guide
node_factory_guide -->|"activates lifecycle"| node_build_command
node_build_command -->|"uses contract"| node_skill_template
node_build_command -->|"uses contract"| node_agent_template
node_build_command -->|"uses contract"| node_hook_template
node_skills_guide -->|"creates via"| node_prompt_factory
node_build_command -->|"generates via"| node_agent_factory
node_hooks_guide -->|"creates via"| node_hook_factory
node_hook_factory -->|"validates output"| node_hook_validator
node_validate_command -->|"invokes"| node_hook_validator
node_hook_validator -->|"approves for install"| node_hook_installer
node_install_command -->|"invokes"| node_hook_installer
node_agent_factory -->|"writes"| node_generated_agents
node_build_command -->|"writes"| node_generated_commands
node_hook_installer -->|"installs"| node_generated_hooks
node_codex_bridge -->|"guarded by"| node_bridge_safety
node_generated_agents -.->|"Claude guidance source"| node_codex_bridge
node_generated_hooks -.->|"can automate GitHub flows"| node_github_workflows
node_github_workflows -.->|"governs repository changes"| node_generated_commands

click node_claude "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/CLAUDE.md"
click node_factory_guide "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/factory-guide.md"
click node_skills_guide "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/skills-guide.md"
click node_hooks_guide "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/hooks-guide.md"
click node_build_command "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/build.md"
click node_validate_command "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/validate-output.md"
click node_install_command "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/install-skill.md"
click node_skill_template "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/SKILLS_FACTORY_PROMPT.md"
click node_agent_template "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/AGENTS_FACTORY_PROMPT.md"
click node_hook_template "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/HOOKS_FACTORY_PROMPT.md"
click node_prompt_factory "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/prompt-factory/SKILL.md"
click node_agent_factory "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/agent_generator.py"
click node_hook_factory "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/hook_factory.py"
click node_hook_validator "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/validator.py"
click node_hook_installer "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/installer.py"
click node_codex_bridge "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/codex-cli-bridge/bridge.py"
click node_bridge_safety "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/codex-cli-bridge/safety_mechanism.py"
click node_github_workflows "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.github/workflows/ci-quality-gate.yml"
click node_generated_agents "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-agents/claude-md-guardian/claude-md-guardian.md"
click node_generated_commands "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-commands/enhance-claude-md/enhance-claude-md.md"
click node_generated_hooks "https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-hooks/auto-sync-plan-to-github/hook.json"

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_claude,node_factory_guide,node_skills_guide,node_hooks_guide,node_build_command,node_validate_command,node_install_command toneBlue
class node_skill_template,node_agent_template,node_hook_template toneAmber
class node_prompt_factory,node_agent_factory,node_hook_factory,node_hook_validator,node_hook_installer toneMint
class node_generated_agents,node_generated_commands,node_generated_hooks toneRose
class node_codex_bridge,node_bridge_safety,node_github_workflows toneIndigo
```

## Components

### Factory Control

Declarative Claude Code entry points and orchestration.

- [Repository guidance](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/CLAUDE.md): Claude instructions · Top-level guidance for using the factory. · `CLAUDE.md`
- [Factory guide](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/factory-guide.md): conversational router · Collects artifact requests and delegates to specialist guides. · `.claude/agents/factory-guide.md`
- [Skills guide](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/skills-guide.md): specialist guide · Runs the interactive skill-creation workflow. · `.claude/agents/skills-guide.md`
- [Hooks guide](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/agents/hooks-guide.md): specialist guide · Runs the interactive hook-creation workflow. · `.claude/agents/hooks-guide.md`
- [Build command](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/build.md): slash command · Coordinates requirement collection and artifact generation. · `.claude/commands/build.md`
- [Validate output](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/validate-output.md): slash command · Checks generated artifacts before use. · `.claude/commands/validate-output.md`
- [Install skill](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.claude/commands/install-skill.md): slash command · Installs validated skills into Claude Code locations. · `.claude/commands/install-skill.md`

### Generation Contracts

Templates define compatible artifact structure and safety expectations.

- [Skills factory contract](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/SKILLS_FACTORY_PROMPT.md): generation template · Defines skill metadata, layout, samples, and conventions. · `documentation/templates/SKILLS_FACTORY_PROMPT.md`
- [Agents factory contract](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/AGENTS_FACTORY_PROMPT.md): generation template · Defines generated agent output requirements. · `documentation/templates/AGENTS_FACTORY_PROMPT.md`
- [Hooks factory contract](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/documentation/templates/HOOKS_FACTORY_PROMPT.md): generation template · Defines hook safety and platform conventions. · `documentation/templates/HOOKS_FACTORY_PROMPT.md`

### Installable Skill Packages

Independent generated packages with specialized implementations.

- [Prompt factory](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/prompt-factory/SKILL.md): skill package · Independently installable prompt-generation skill. · `generated-skills/prompt-factory/SKILL.md`
- [Agent factory](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/agent_generator.py): Python generator · Generates declarative Claude Code agents. · `generated-skills/agent-factory/agent_generator.py`
- [Hook factory](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/hook_factory.py): Python package · Generates and prepares executable hook artifacts. · `generated-skills/hook-factory/hook_factory.py`
- [Hook validator](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/validator.py): validation layer · Safety and correctness control before installation. · `generated-skills/hook-factory/validator.py`
- [Hook installer](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/hook-factory/installer.py): installation layer · Applies validated hooks to local Claude configuration. · `generated-skills/hook-factory/installer.py`

### Generated Outputs

Ready-to-use extensions and distributable artifacts.

- [Generated agents](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-agents/claude-md-guardian/claude-md-guardian.md): declarative output · Ready-to-use Claude Code agents. · `generated-agents/claude-md-guardian/claude-md-guardian.md`
- [Generated commands](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-commands/enhance-claude-md/enhance-claude-md.md): declarative output · Ready-to-use slash-command extensions. · `generated-commands/enhance-claude-md/enhance-claude-md.md`
- [Generated hooks](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-hooks/auto-sync-plan-to-github/hook.json): hook output · Installable hook configuration artifacts. · `generated-hooks/auto-sync-plan-to-github/hook.json`

### External Automation

Cross-tool execution and repository governance.

- [Codex bridge](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/codex-cli-bridge/bridge.py): cross-tool bridge · Derives Codex guidance and executes Codex workflows. · `generated-skills/codex-cli-bridge/bridge.py`
- [Bridge safety](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/codex-cli-bridge/safety_mechanism.py): safety layer · Guards local Codex CLI operations. · `generated-skills/codex-cli-bridge/safety_mechanism.py`
- [GitHub workflows](https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/.github/workflows/ci-quality-gate.yml): GitHub Actions · Quality gates and plan-to-task repository automation. · `.github/workflows/ci-quality-gate.yml`

## Connections

- Repository guidance → Factory guide: guides use of
- Factory guide → Skills guide: delegates skills
- Factory guide → Hooks guide: delegates hooks
- Factory guide → Build command: activates lifecycle
- Build command → Skills factory contract: uses contract
- Build command → Agents factory contract: uses contract
- Build command → Hooks factory contract: uses contract
- Skills guide → Prompt factory: creates via
- Build command → Agent factory: generates via
- Hooks guide → Hook factory: creates via
- Hook factory → Hook validator: validates output
- Validate output → Hook validator: invokes
- Hook validator → Hook installer: approves for install
- Install skill → Hook installer: invokes
- Agent factory → Generated agents: writes
- Build command → Generated commands: writes
- Hook installer → Generated hooks: installs
- Codex bridge → Bridge safety: guarded by
- Generated agents → Codex bridge: Claude guidance source
- Generated hooks → GitHub workflows: can automate GitHub flows
- GitHub workflows → Generated commands: governs repository changes