How alirezarezvani/claude-code-skill-factory works
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: build.md Build command · factory-guide.md Factory guide · validator.py Hook validator · installer.py Hook installer
Components 21
Factory Control
Declarative Claude Code entry points and orchestration.
- Repository guidance · Top-level guidance for using the factory.
CLAUDE.md - Factory guide · Collects artifact requests and delegates to specialist guides.
.claude/agents/factory-guide.md - Skills guide · Runs the interactive skill-creation workflow.
.claude/agents/skills-guide.md - Hooks guide · Runs the interactive hook-creation workflow.
.claude/agents/hooks-guide.md - Build command · Coordinates requirement collection and artifact generation.
.claude/commands/build.md - Validate output · Checks generated artifacts before use.
.claude/commands/validate-output.md - Install skill · 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 · Defines skill metadata, layout, samples, and conventions.
documentation/templates/SKILLS_FACTORY_PROMPT.md - Agents factory contract · Defines generated agent output requirements.
documentation/templates/AGENTS_FACTORY_PROMPT.md - Hooks factory contract · Defines hook safety and platform conventions.
documentation/templates/HOOKS_FACTORY_PROMPT.md
Installable Skill Packages
Independent generated packages with specialized implementations.
- Prompt factory · Independently installable prompt-generation skill.
generated-skills/prompt-factory/SKILL.md - Agent factory · Generates declarative Claude Code agents.
generated-skills/agent-factory/agent_generator.py - Hook factory · Generates and prepares executable hook artifacts.
generated-skills/hook-factory/hook_factory.py - Hook validator · Safety and correctness control before installation.
generated-skills/hook-factory/validator.py - Hook installer · Applies validated hooks to local Claude configuration.
generated-skills/hook-factory/installer.py
Generated Outputs
Ready-to-use extensions and distributable artifacts.
- Generated agents · Ready-to-use Claude Code agents.
generated-agents/claude-md-guardian/claude-md-guardian.md - Generated commands · Ready-to-use slash-command extensions.
generated-commands/enhance-claude-md/enhance-claude-md.md - Generated hooks · Installable hook configuration artifacts.
generated-hooks/auto-sync-plan-to-github/hook.json
External Automation
Cross-tool execution and repository governance.
- Codex bridge · Derives Codex guidance and executes Codex workflows.
generated-skills/codex-cli-bridge/bridge.py - Bridge safety · Guards local Codex CLI operations.
generated-skills/codex-cli-bridge/safety_mechanism.py - GitHub workflows · Quality gates and plan-to-task repository automation.
.github/workflows/ci-quality-gate.yml
Connections 21
- 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