Skip to content

About

An open-source guide and starter template for AI-ready repositories. Learn AGENTS.md, CLAUDE.md, Claude Code, GitHub Copilot, OpenAI Codex, agent skills, custom agents, instructions, and hooks through practical examples.

Topics

Resources

Contributing

Stars

12 stars

Watchers

0 watching

Forks

Repository files navigation

Ignite UI

AI Repo Structure - Build AI-Ready Repositories

A working reference for structuring AI-enabled repositories:
AGENTS.md, CLAUDE.md, instructions, custom agents, skills, and hooks for Claude Code, GitHub Copilot, and OpenAI Codex, each in the right place.

GitHub stars MIT License Learning Course Live Docs

Course · Docs site · Quick start · Contributing


Why this exists

Adding AI coding tools to a repo usually starts with one instruction file and grows into a mess:

  • one giant instruction file that tries to do every job
  • no clear answer to what belongs in AGENTS.md, CLAUDE.md, rules, agents, skills, or hooks
  • Claude Code, GitHub Copilot, and Codex setups that drift apart or duplicate each other

This repository shows a clean alternative. It is a template, a reference implementation, and a learning repo at the same time: its own AI setup is real, in use, and part of the lesson.

It is for developers building an AI-enabled repo from scratch, teams cleaning up an existing AI setup, and maintainers who want internal AI helpers for review, structure, and documentation.


Which file does which job

File or folder Job
AGENTS.md Shared always-on rules for all coding agents
CLAUDE.md Claude-only always-on rules
.github/copilot-instructions.md Copilot-only always-on rules
.instructions.md / .claude/rules/ Scoped rules for certain files or folders
Custom agents Specialist roles
Skills (SKILL.md) Reusable multi-step workflows
Hooks Small, deterministic actions at known events

The full decision table, with when to use each one and what not to use it for, is in LEARN.md.


Claude Code vs GitHub Copilot vs OpenAI Codex

Job Claude Code GitHub Copilot OpenAI Codex
Shared instructions AGENTS.md via @AGENTS.md in CLAUDE.md AGENTS.md AGENTS.md
Tool-specific instructions CLAUDE.md .github/copilot-instructions.md none
Path-scoped instructions .claude/rules/ .github/instructions/ nested AGENTS.md
Project skills .claude/skills/ .github/skills/, .claude/skills/, .agents/skills/ .agents/skills/
Custom agents .claude/agents/*.md .github/agents/*.agent.md .codex/agents/*.toml
Hooks .claude/settings.json .github/hooks/*.json .codex/hooks.json

The detailed version, with how each tool loads these files, is in LEARN.md.


What's inside

Layer Location For Contains
Shared root README.md, LEARN.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md Humans and all agents Entry point, course, shared agent rules, Claude rules, contributor workflow
Internal Claude .claude/ Maintainers using Claude Code A scoped rule, the learning-repo-maintainer agent, the validate-learning-repo skill, a SessionStart hook in settings.json
Internal GitHub/Copilot .github/ Maintainers using GitHub Copilot Repo-wide and path-specific instructions, the learning-repo-maintainer agent, the review-learning-repo-pr skill, an optional sessionStart hook for Copilot CLI and Copilot cloud agent
Internal Codex .codex/ Maintainers using OpenAI Codex The learning_repo_maintainer agent, a SessionStart hook in hooks.json
Cross-agent skills .agents/skills/ Codex and Copilot, discovered automatically The sync-agent-layers skill that keeps the three tool layers aligned
Shared skills skills/ Users of the repo and outside agents use-this-repo to understand the structure, adopt-this-repo to plan adoption in another project
Hook support scripts/hooks/ Hook runtimes Small scripts that give agents session-start context and checks
Application source src/ Developers The landing page source, standing in for a real project's application code
Docs site docs/ Search and browsing The public GitHub Pages site, with published copies of the src/ files

The Claude, Copilot, and Codex layers mirror each other on purpose, so you can compare the same idea across tools.

skills/ is a distribution layer: coding agents do not load it automatically. To use a skill, copy it into .claude/skills/, .github/skills/, or .agents/skills/, or point an agent at its SKILL.md. Skills already in .agents/skills/ are different: Codex and Copilot discover them automatically while working in this repo.

Show how the layers connect (diagram)
flowchart TB
  subgraph root["Shared root"]
    README["README.md<br/>Human entry point"]
    LEARN["LEARN.md<br/>Guided course"]
    AGENTS["AGENTS.md<br/>Shared agent rules"]
    CLAUDE["CLAUDE.md<br/>Claude context"]
  end

  subgraph claude["Internal Claude"]
    CR[".claude/rules/"]
    CA[".claude/agents/"]
    CS[".claude/skills/"]
    CH[".claude/settings.json<br/>hooks"]
  end

  subgraph copilot["Internal GitHub Copilot"]
    GCI[".github/copilot-instructions.md"]
    GI[".github/instructions/"]
    GA[".github/agents/"]
    GS[".github/skills/"]
    GH[".github/hooks/"]
  end

  subgraph codex["Internal Codex"]
    XA[".codex/agents/"]
    XH[".codex/hooks.json"]
  end

  XS[".agents/skills/<br/>Cross-agent skills"]
  SK["skills/<br/>Shared skills, not auto-loaded"]
  HS["scripts/hooks/<br/>Hook scripts"]

  README --> LEARN
  CLAUDE -- "imports" --> AGENTS
  CLAUDE --> claude
  AGENTS -. "read by" .-> copilot
  AGENTS -. "read directly by" .-> codex
  XS -. "discovered by" .-> copilot
  XS -. "discovered by" .-> codex
  CH --> HS
  GH --> HS
  XH --> HS
Loading

The diagram shows which files explain the repo, which files guide tools, and which folders contain reusable workflows or automation.


Quick start

Clone the repository:

git clone https://github.com/IgniteUI/ai-repo-structure.git

Then pick a path.

1. Learn the structure. Read LEARN.md. Each module explains one file type and gives you a template and a real example from this repo.

2. Copy the minimal setup. Most repos only need this to start:

  • README.md
  • AGENTS.md
  • one always-on file for the tool you use: CLAUDE.md or .github/copilot-instructions.md (Codex needs none; it reads AGENTS.md directly)

Start from the templates in Module 2, Module 3, and Module 8. Add rules, agents, skills, and hooks only when a real need appears. The adoption levels describe when to move from minimal to practical or full.

3. Let your coding agent plan it. Point Claude Code, GitHub Copilot, Codex, or another agent at the adoption skill:

Follow skills/adopt-this-repo/SKILL.md to create an adoption plan for my project at <path-to-your-repo>.

It returns a plan split into must-have, good-to-have, and optional, with what to copy now, adapt later, or skip.


The course

LEARN.md is a practical course with 17 modules. Every module covers what the file is for, how to write its description, best practices, a copyable template, and a real example from this repository.

Area Modules
Shared root 1. README.md · 2. AGENTS.md
Claude 3. CLAUDE.md · 4. Rules · 5. Agents · 6. Skills · 7. Settings and hooks
GitHub Copilot 8. Repo-wide instructions · 9. Path-specific instructions · 10. Agents · 11. Skills · 12. Hooks
OpenAI Codex 15. Custom agents · 16. Hooks
Shared 13. Shared skills · 14. Hook support scripts · 17. Cross-agent skills

It ends with a good rollout order and common mistakes, and includes a cross-agent compatibility table.


Core ideas

  1. AI files should have clear roles. Not everything belongs in one giant instruction file.
  2. Internal and external AI layers should be separate. Maintainer AI (.claude/, .github/, .codex/, .agents/skills/) is different from user-facing AI (skills/).
  3. Each file type does a different job. Rules and instructions are guidance, agents are specialized roles, skills are reusable workflows, and hooks are optional deterministic automation for supported runtimes.
  4. Hooks stay small and low-risk. Here they only run at session start: Claude and Codex receive a one-line repo check result, and Copilot CLI or cloud agent can run a quick check of core files.
  5. A template repo should still feel real. Meaningful files and realistic relationships teach more than an empty folder tree.

Repository structure

Show the full repository tree
ai-repo-structure/
├─ .agents/                                      # Cross-agent layer discovered automatically by Codex and Copilot
│  └─ skills/
│     └─ sync-agent-layers/                      # Skill that carries relevant changes across the Claude, Copilot, and Codex layers
│        ├─ references/
│        │  └─ counterparts.md                   # Which file in each tool layer does the same job
│        └─ SKILL.md                             # Cross-agent skill definition and workflow
│
├─ .claude/                                      # Internal Claude layer for repo maintainers
│  ├─ agents/                                    # Claude subagents specialized for this repo
│  │  └─ learning-repo-maintainer.md             # Claude agent that maintains repo structure and learning quality
│  ├─ rules/                                     # Always-on or scoped Claude guidance for this repo
│  │  └─ repo-learning.md                        # Rule that keeps the repo accurate as a teaching/learning repo
│  ├─ skills/                                    # Claude skills for repeatable internal maintainer workflows
│  │  └─ validate-learning-repo/                 # Claude skill that audits whether the repo still matches what it teaches
│  │     ├─ assets/                              # Reusable output resources for the skill
│  │     │  └─ report-template.md                # Template for reporting validation results
│  │     ├─ references/                          # Supporting docs the skill reads while working
│  │     │  └─ checklist.md                      # Checklist for validating structure, naming, and teaching quality
│  │     ├─ scripts/                             # Helper scripts used by the skill
│  │     │  └─ check-required-files.sh           # Script that checks required repo files and that docs/ matches src/
│  │     └─ SKILL.md                             # Main Claude skill definition and workflow instructions
│  └─ settings.json                              # Claude project settings; needed here because Claude project hooks live here
│
├─ .codex/                                       # Internal Codex layer for repo maintainers
│  ├─ agents/                                    # Codex custom agents for this repo
│  │  └─ learning_repo_maintainer.toml           # Codex maintainer agent for repo structure and learning content
│  └─ hooks.json                                 # Codex SessionStart hook that reports the repo check result
│
├─ .github/                                      # Internal GitHub/Copilot layer for repo maintainers
│  ├─ agents/                                    # Custom GitHub Copilot agents for this repo
│  │  └─ learning-repo-maintainer.agent.md       # GitHub-side maintainer agent for repo structure and learning content
│  ├─ instructions/                              # Path-specific Copilot instructions
│  │  └─ learning-content.instructions.md        # Copilot guidance for README, AGENTS, CLAUDE, and other teaching content
│  ├─ hooks/                                     # GitHub/Copilot workspace hook configs
│  │  └─ session-start-check.json                # Official sessionStart hook config for validating core repo guidance
│  ├─ skills/                                    # GitHub Copilot skills for repeatable maintainer workflows
│  │  └─ review-learning-repo-pr/                # GitHub skill for reviewing PRs that change the repo's learning structure
│  │     ├─ assets/                              # Reusable review output resources
│  │     │  └─ review-template.md                # Template for writing PR review findings
│  │     ├─ references/                          # Supporting docs for the review skill
│  │     │  └─ review-checklist.md               # Checklist for reviewing structure, naming, and correctness
│  │     ├─ scripts/                             # Helper scripts used by the review skill
│  │     │  └─ list-learning-files.sh            # Script that lists learning-related files changed in a PR
│  │     └─ SKILL.md                             # Main GitHub skill definition and PR review workflow
│  └─ copilot-instructions.md                    # Main repo-wide GitHub Copilot instructions
│
├─ skills/                                       # External/shared skills for users of the repo and outside agents
│  ├─ README.md                                  # Overview of the available shared skills
│  ├─ use-this-repo/                             # Shared skill for understanding the repo structure and layers
│  │  ├─ references/                             # Supporting docs for understanding the repo
│  │  │  └─ repo-map.md                          # Explanation of the repo layers and what each one is for
│  │  ├─ scripts/                                # Helper scripts for external/shared usage
│  │  │  └─ quickstart-check.sh                  # Script that checks whether the expected starter structure exists
│  │  └─ SKILL.md                                # Main shared skill definition for understanding the repo
│  └─ adopt-this-repo/                           # Shared skill for adopting this AI structure into another project
│     ├─ assets/                                 # Reusable templates for adoption output
│     │  └─ adoption-plan-template.md            # Template for producing a practical adoption plan
│     ├─ references/                             # Supporting docs for adoption decisions
│     │  ├─ repo-map.md                          # Summary of the repo layers and their jobs
│     │  ├─ adoption-levels.md                   # Minimal, practical, and full adoption levels
│     │  └─ copy-vs-adapt.md                     # What to copy, adapt, rename, or skip
│     ├─ scripts/                                # Helper scripts for adoption checks
│     │  └─ quickstart-check.sh                  # Optional script for checking a target repo's starter structure
│     └─ SKILL.md                                # Main shared skill definition for adoption planning
│
├─ docs/                                         # Public documentation site for GitHub Pages and search indexing
│  ├─ _config.yml                                # GitHub Pages / Jekyll site configuration
│  ├─ index.html                                 # Published copy of src/index.html for GitHub Pages
│  ├─ styles.css                                 # Published copy of src/styles.css
│  ├─ app.js                                     # Published copy of src/app.js
│  ├─ read.md                                    # Markdown overview page, published at /overview/
│  ├─ repo-structure.md                          # Page explaining the repository structure and each main layer
│  ├─ claude-vs-copilot.md                       # Page comparing the Claude, GitHub Copilot, and Codex parts
│  ├─ getting-started.md                         # Page showing how to use this repo as a starter, reference, or learning repo
│  ├─ googlecad1e2aef0d47fd8.html                # Google Search Console verification file
│  ├─ robots.txt                                 # Search engine crawler instructions for the public docs site
│  └─ sitemap.xml                                # List of site pages to help search engines discover them
│
├─ public/                                       # Static assets used by the README
│  └─ assets/
│     └─ igniteui.svg                            # Repository svg
│
├─ scripts/                                      # Shared repo utility scripts
│  └─ hooks/                                     # Helper scripts used by Claude, GitHub/Copilot, and Codex hooks
│     ├─ github-session-start-check.sh           # Bash sessionStart check for GitHub Copilot hooks
│     └─ session-start-context.sh                # Reports the repo check result to Claude and Codex at SessionStart
│
├─ src/                                          # Application source: the AI Repo Map landing page; edit here
│  ├─ index.html                                 # Landing page markup, metadata, and static content
│  ├─ styles.css                                 # Landing page styles
│  └─ app.js                                     # Script that renders the directory tree and page effects
│
├─ AGENTS.md                                     # Shared agent-facing instructions for coding agents working in the repo
├─ CLAUDE.md                                     # Main Claude-specific project guidance
├─ CONTRIBUTING.md                               # Contributor workflow guidance for keeping the repo accurate and aligned
├─ LEARN.md                                      # Course for understanding and copying the system
├─ LICENSE                                       # MIT license
└─ README.md                                     # Main human entry point

Contributing

Contributions that keep the repo accurate and practical are welcome. Read CONTRIBUTING.md first. The main rule is that the repo must teach exactly the structure it contains.

If this repo helped you decide where an AI instruction belongs, a ⭐ helps other developers find it.

License

MIT

About

An open-source guide and starter template for AI-ready repositories. Learn AGENTS.md, CLAUDE.md, Claude Code, GitHub Copilot, OpenAI Codex, agent skills, custom agents, instructions, and hooks through practical examples.

Topics

Resources

Contributing

Stars

12 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages