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.
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.
| 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.
| 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.
| 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
The diagram shows which files explain the repo, which files guide tools, and which folders contain reusable workflows or automation.
Clone the repository:
git clone https://github.com/IgniteUI/ai-repo-structure.gitThen 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.mdAGENTS.md- one always-on file for the tool you use:
CLAUDE.mdor.github/copilot-instructions.md(Codex needs none; it readsAGENTS.mddirectly)
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.
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.
- AI files should have clear roles. Not everything belongs in one giant instruction file.
- Internal and external AI layers should be separate. Maintainer AI (
.claude/,.github/,.codex/,.agents/skills/) is different from user-facing AI (skills/). - 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.
- 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.
- A template repo should still feel real. Meaningful files and realistic relationships teach more than an empty folder tree.
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
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.