SYS.READY // X:000 Y:000
ID: IGNITE-UI/AI-REPO-STRUCTURE
[ LEARNING REPOSITORY MAP ]

AI REPO
STRUCTURE

A practical reference blueprint for structuring a real AI-enabled project. Separating shared guidance, internal Claude, Copilot, and Codex configurations, and repeatable external skills.

01

SYSTEM LAYERS

Drill down from shared root context to tool-specific automation.

Shared Root

THE CORE DIRECTORY

These files explain the repo, guide contributors, and give the main shared context before tool-specific behavior begins.

  • README.md — Main entry point
  • LEARN.md — Guided course
  • AGENTS.md — Shared agent rules
  • CLAUDE.md — Claude context
Internal / Claude

.claude/

Claude-specific rules, agents, skills, and settings live here. This layer supports structured Claude maintainer workflows.

  • rules/ — Scoped guidance
  • agents/ — Specialist roles
  • skills/ — Repeatable workflows
  • settings.json — Hooks config
Internal / Copilot

.github/

GitHub/Copilot instructions, agents, skills, and hook configs live here. Hand-crafted for GitHub-side behavior.

  • copilot-instructions.md — Repo guidance
  • instructions/ — Path-specific context
  • agents/ — Copilot roles
  • hooks/ — Automation
Internal / Codex

.codex/

Codex custom agents and hooks live here. Codex reads AGENTS.md directly, so this layer needs no instruction file.

  • agents/ — Custom agents (TOML)
  • hooks.json — Session-start hook
Cross-agent / Codex + Copilot

.agents/skills/

Maintainer skills that Codex and Copilot discover automatically. Claude Code does not scan this folder.

  • sync-agent-layers/ — Keeps tool layers aligned
  • SKILL.md — Workflow definition
  • references/ — Supporting docs
External / Public

skills/

This is the reusable public-facing workflow layer. It is meant for users of the repo and outside agents, not only maintainers.

  • SKILL.md — Workflow definition
  • assets/ — Templates
  • references/ — Supporting docs
  • scripts/ — Executables
02

DIRECTORY TREE

The physical manifestation of the architecture.

~/ignite-ui/ai-repo-structure tree -a -C

The tree needs JavaScript. See the full tree in the README.

03

EXECUTION PATH

Recommended sequence for parsing the repository context.

  1. 01
    README.md — Understand the purpose and the main structure.
  2. 02
    LEARN.md — Follow the guided course for how the pieces fit together.
  3. 03
    AGENTS.md — See the shared working rules for agents.
  4. 04
    CLAUDE.md — Understand Claude-specific project context.
  5. 05
    .claude/, .github/, and .codex/ — Inspect the internal maintainer layers.
  6. 06
    .agents/skills/ — See the cross-agent skills that Codex and Copilot discover automatically.
  7. 07
    skills/ — Explore the reusable external workflows.
  8. 08
    scripts/hooks/ — See how session-start context support is implemented.