yangjinmin666/github-architecture-analyzer-skill

This project is a Codex Skill, a plug-in style tool that adds a new ability to the Codex coding assistant. Its job is to take a GitHub repository link or a local repo path and produce a plain-language architecture analysis document for it. The idea is that anyone looking at an unfamiliar codebase, whether they work in product, design, operations, or engineering, can get a shared picture of how the project actually works. When pointed at a repository, the skill reads the code, configuration files, documentation, and folder structure. It figures out what kind of project it is, such as a frontend app, backend service, full stack app, AI agent, command line tool, plugin, mini program, component library, mobile app, desktop app, infrastructure project, or a monorepo containing several of these. It then breaks the project down into its technology choices, the responsibilities of each folder, how modules connect, and how a request or user action flows through the system from click to result. For projects built around AI agents specifically, it goes further and separates out the pieces that matter for that style of system: the graph of steps, the state being tracked, individual nodes, prompts, tools, memory, and any points where a human needs to step in. The output is a Markdown document containing Mermaid diagrams, structured into sections like an executive summary, a repository map, module breakdown, the core runtime flow, data and external interfaces, design tradeoffs, and known risks or gaps. Claims in the document are meant to be traceable back to actual evidence in the README, config, or source files rather than guessed. Setup is simple: copy the github-architecture-analyzer folder into your local Codex skills directory and restart Codex. The repository also ships a small Python helper script that scans a repo and outputs a JSON inventory of its files, languages, config files, tests, and routes. It is licensed under MIT.