# am-will/codex-skills architecture

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

- Interactive diagram: https://gitdiagram.com/am-will/codex-skills
- Repository: https://github.com/am-will/codex-skills

## Overview

CodexSkills is a repository of reusable agent skills, custom Codex agent definitions, and installable hook bundles, with a small CLI for copying skills from Git repositories. A user selects a capability, installs it into an agent or project, then uses its instructions or configuration; hooks are separately installed into a project. The llm-council skill adds a multi-provider planning workflow with a live review UI. Evidence for broad catalog relationships comes from the README; source excerpts additionally establish the council UI/state links. Other skill internals are not sampled.

Main entry points: [`skills/llm-council/scripts/llm_council.py`](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/llm_council.py) (Council Runner), [`skills/llm-council/scripts/ui_server.py`](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui_server.py) (Review UI Server), [`hooks/aitmpl-codex/install-bundle.py`](https://github.com/am-will/codex-skills/blob/main/hooks/aitmpl-codex/install-bundle.py) (Bundle Installer), [`skills`](https://github.com/am-will/codex-skills/tree/main/skills) (Skill Collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Skill Catalog"]
  node_skillsrepo["Skill Collection"]
  node_planning["Planning Skills"]
  node_docsaccess["Documentation Access"]
  node_frontend["Frontend Guidance"]
  node_browser["Browser Automation"]
end

subgraph group_orchestration["Planning Orchestration"]
  node_council["Council Runner<br/>[llm_council.py]"]
  node_uiserver["Review UI Server<br/>[ui_server.py]"]
  node_uistate[("UI State<br/>[ui_state.py]")]
  node_uiapp["Review UI<br/>[app.js]"]
end

subgraph group_agents["Agent Configurations"]
  node_agentdefs["Specialist Agents"]
end

subgraph group_hooks["Hook Bundles"]
  node_hookcatalog["Hook Catalog"]
  node_hookinstaller["Bundle Installer<br/>[install-bundle.py]"]
end

node_user(("User"))
node_skillscli["Skills CLI"]
node_providers(("AI Providers"))
node_projecthooks["Project Hook Config"]
node_skillsinstaller["Skills Installer"]

node_user -->|"selects skills"| node_skillsinstaller
node_skillsinstaller -->|"installs from"| node_skillsrepo
node_user -->|"runs CLI"| node_skillscli
node_skillscli -->|"copies skills"| node_skillsrepo
node_user -->|"uses planning"| node_planning
node_user -->|"uses docs tools"| node_docsaccess
node_user -->|"uses guidance"| node_frontend
node_user -->|"runs browser agent"| node_browser
node_user -->|"starts planning"| node_council
node_council -->|"requests plans"| node_providers
node_council -->|"starts UI server"| node_uiserver
node_uiserver -->|"reads UI state"| node_uistate
node_uiapp -->|"fetches and posts"| node_uiserver
node_user -->|"configures agents"| node_agentdefs
node_user -->|"chooses bundle"| node_hookcatalog
node_user -->|"installs bundle"| node_hookinstaller
node_hookinstaller -->|"merges configuration"| node_projecthooks

click node_skillsrepo "https://github.com/am-will/codex-skills/tree/main/skills"
click node_planning "https://github.com/am-will/codex-skills/tree/main/skills/planner"
click node_docsaccess "https://github.com/am-will/codex-skills/tree/main/skills/read-github"
click node_frontend "https://github.com/am-will/codex-skills/tree/main/skills/frontend-design"
click node_browser "https://github.com/am-will/codex-skills/tree/main/skills/gemini-computer-use"
click node_council "https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/llm_council.py"
click node_uiserver "https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui_server.py"
click node_uistate "https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui_state.py"
click node_uiapp "https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui/app.js"
click node_agentdefs "https://github.com/am-will/codex-skills/tree/main/agents"
click node_hookcatalog "https://github.com/am-will/codex-skills/tree/main/hooks/aitmpl-codex"
click node_hookinstaller "https://github.com/am-will/codex-skills/blob/main/hooks/aitmpl-codex/install-bundle.py"

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_skillsrepo,node_planning,node_docsaccess,node_frontend,node_browser,node_user toneBlue
class node_council,node_uiserver,node_uistate,node_uiapp toneAmber
class node_agentdefs toneMint
class node_hookcatalog,node_hookinstaller toneRose
class node_skillscli,node_providers,node_projecthooks,node_skillsinstaller toneIndigo
```

## Components

### Skill Catalog

- [Skill Collection](https://github.com/am-will/codex-skills/tree/main/skills): `skills`
- [Planning Skills](https://github.com/am-will/codex-skills/tree/main/skills/planner): `skills/planner`
- [Documentation Access](https://github.com/am-will/codex-skills/tree/main/skills/read-github): `skills/read-github`
- [Frontend Guidance](https://github.com/am-will/codex-skills/tree/main/skills/frontend-design): `skills/frontend-design`
- [Browser Automation](https://github.com/am-will/codex-skills/tree/main/skills/gemini-computer-use): `skills/gemini-computer-use`

### Planning Orchestration

- [Council Runner](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/llm_council.py): `skills/llm-council/scripts/llm_council.py`
- [Review UI Server](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui_server.py): `skills/llm-council/scripts/ui_server.py`
- [UI State](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui_state.py): `skills/llm-council/scripts/ui_state.py`
- [Review UI](https://github.com/am-will/codex-skills/blob/main/skills/llm-council/scripts/ui/app.js): `skills/llm-council/scripts/ui/app.js`

### Agent Configurations

- [Specialist Agents](https://github.com/am-will/codex-skills/tree/main/agents): `agents`

### Hook Bundles

- [Hook Catalog](https://github.com/am-will/codex-skills/tree/main/hooks/aitmpl-codex): `hooks/aitmpl-codex`
- [Bundle Installer](https://github.com/am-will/codex-skills/blob/main/hooks/aitmpl-codex/install-bundle.py): `hooks/aitmpl-codex/install-bundle.py`

### Other components

- **User**
- **Skills CLI**
- **AI Providers**
- **Project Hook Config**
- **Skills Installer**

## Connections

- User → Skills Installer: selects skills (evidence: `README.md`)
- Skills Installer → Skill Collection: installs from (evidence: `README.md`)
- User → Skills CLI: runs CLI
- Skills CLI → Skill Collection: copies skills
- User → Planning Skills: uses planning (evidence: `README.md`)
- User → Documentation Access: uses docs tools (evidence: `README.md`)
- User → Frontend Guidance: uses guidance (evidence: `README.md`)
- User → Browser Automation: runs browser agent (evidence: `README.md`)
- User → Council Runner: starts planning (evidence: `README.md`)
- Council Runner → AI Providers: requests plans (evidence: `README.md`)
- Council Runner → Review UI Server: starts UI server (evidence: `skills/llm-council/scripts/llm_council.py`)
- Review UI Server → UI State: reads UI state (evidence: `skills/llm-council/scripts/ui_server.py`)
- Review UI → Review UI Server: fetches and posts (evidence: `README.md`)
- User → Specialist Agents: configures agents (evidence: `README.md`)
- User → Hook Catalog: chooses bundle (evidence: `README.md`)
- User → Bundle Installer: installs bundle (evidence: `README.md`)
- Bundle Installer → Project Hook Config: merges configuration (evidence: `hooks/aitmpl-codex/install-bundle.py`)