A practical learning repository for structuring a real AI-enabled project
with shared instructions, Claude-specific configuration, GitHub/Copilot configuration, hooks, and reusable skills.
ai-repo-structure is a real learning repository that demonstrates how to structure a project around modern AI coding tools in a way that is practical, understandable, and reusable from the AI agents.
This is not just a mock folder tree.
It is a working reference repo whose own AI setup is part of the lesson.
It shows how to combine:
- shared agent instructions with
AGENTS.md - Claude-specific guidance with
CLAUDE.md - contributor workflow guidance with
CONTRIBUTING.md - internal Claude rules, agents, skills, and hooks in
.claude/ - internal GitHub Copilot instructions, agents, skills, and optional Copilot coding agent hooks in
.github/ - external/shared skills in
skills/ - course for understanding and copying the system
LEARN.md
- ai-repo-structure
- Overview
- Quick navigation
- Who this is for
- Learn this repo
- Why this repo exists
- How to read this repo
- How the AI layers connect
- This diagram shows which files explain the repo, which files guide tools, and which folders contain reusable workflows or automation.
- Current project structure
- Shared root layer
- Internal Claude layer
- Internal GitHub/Copilot layer
- Shared external skills
- Support scripts
- What hooks are doing here
- What this repo is demonstrating
- Current status
- One-line description
This repo is for:
- developers building an AI-enabled repo from scratch
- teams that want a cleaner AI setup
- people learning what each AI-related file is for
- maintainers who want internal AI helpers for review, structure, and documentation
- anyone who wants a repo that is both a template and a teaching example
Want the guided version instead of just the structure?
Read LEARN.md for a short course that explains:
- what each AI layer is for
- a decision table for when to use each instruction type
- how the files relate to each other
- best practices for writing them
- templates you can copy
- real examples you can adapt
This repository helps answer questions like:
- What is
AGENTS.mdfor? - What belongs in
CLAUDE.md? - What is the difference between rules, instructions, agents, skills, and hooks?
- How do I keep an AI repo clean instead of chaotic?
- How do I build a template repo that is also a real example?
So this repo has three jobs at the same time:
- template repo
- reference implementation
- learning repo
A simple reading order is:
README.mdintroduces the repo and points people to the right places.LEARN.mdis the guided course for understanding and copying the system.AGENTS.mdgives shared guidance for coding agents.CLAUDE.mdgives Claude project-specific context.CONTRIBUTING.mdexplains how to make changes without breaking the repo's teaching value..claude/contains Claude-only maintainer pieces..github/contains GitHub/Copilot-only maintainer pieces.skills/contains shared reusable workflows.scripts/hooks/supports hook automation for Claude and GitHub/Copilot.
This diagram shows which files explain the repo, which files guide tools, and which folders contain reusable workflows or automation.
ai-repo-structure/
├─ .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 whether required repo files exist
│ │ └─ SKILL.md # Main Claude skill definition and workflow instructions
│ └─ settings.json # Claude project settings; needed here because Claude project hooks live here
│
├─ .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
│ ├─ use-this-repo/ # Shared skill for understanding the repo structure and layers
│ │ ├─ assets/ # Reusable templates for user-facing outputs
│ │ │ └─ adoption-plan-template.md # Template for suggesting how someone should adopt this repo
│ │ ├─ 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 Google indexing
│ ├─ _config.yml # GitHub Pages / Jekyll site configuration
│ ├─ index.md # Main landing page of the docs site
│ ├─ repo-structure.md # Page explaining the repository structure and each main layer
│ ├─ claude-vs-copilot.md # Page comparing the Claude-specific and GitHub Copilot-specific parts
│ ├─ getting-started.md # Page showing how to use this repo as a starter, reference, or learning repo
│ ├─ robots.txt # Search engine crawler instructions for the public docs site
│ └─ sitemap.xml # List of site pages to help Google and other search engines discover them
│
├─ scripts/ # Shared repo utility scripts
│ └─ hooks/ # Helper scripts used by Claude and GitHub/Copilot hooks
│ ├─ claude-session-context.sh # Emits repo context for Claude SessionStart
│ └─ github-session-start-check.sh # Bash sessionStart check for GitHub Copilot coding agent hooks
│
├─ src/ # Project source area; currently present as the code/application folder
| ├─ index.html # Small HTML shell for the demo page
| ├─ styles.css # Minimal styles for the AI Repo Map layout
| └─ app.js # Small script that renders the repo map content
|
├─ 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
└─ README.md # Main human entry point; will become the learning guide/course for the repo
This is the highest-level explanation layer of the repo.
The human entry point.
It explains:
- what the repo is
- how the layers fit together
- how to read and reuse the structure
The shared instruction file for coding agents.
Think of it as a README for agents:
- setup
- commands
- conventions
- workflow rules
- boundaries
The Claude-specific guide for the project.
It tells Claude:
- what kind of repo this is
- how the repo is organized
- what conventions matter
- how to work safely in this project
The contributor guide for the project.
It explains:
- how to prepare before making changes
- what a good small contribution looks like
- what to validate before opening a pull request
This is the internal Claude maintainer system.
It exists to help maintain the repo itself.
Claude subagents for this repo.
learning-repo-maintainer.md
A focused Claude maintainer for repo structure, learning quality, and consistency.
Claude-scoped project guidance.
repo-learning.md
Keeps the repo accurate as a teaching repo and prevents made-up conventions or mismatched examples.
Reusable Claude maintainer workflows.
A skill that checks whether the repo still matches what it teaches.
One level deeper:
-
assets/
Reusable output pieces used by the skill. -
assets/report-template.md
A template for validation output. -
references/
Supporting docs the skill reads while working. -
references/checklist.md
A checklist for structure, naming, and teaching quality. -
scripts/
Helper scripts used by the skill. -
scripts/check-required-files.sh
Checks whether required files exist. -
SKILL.md
The main skill definition and workflow instructions.
Claude project settings.
In this repo, it matters because Claude hooks are configured through settings and used to inject session-start context.
This is the internal GitHub/Copilot maintainer system.
Its role is similar to .claude/, but on the GitHub side.
The repo-wide Copilot guide.
It gives broad project instructions that should apply across the repository.
Path-specific Copilot guidance.
learning-content.instructions.md
Extra guidance for teaching content such asREADME.md,AGENTS.md,CLAUDE.md, and other repo-learning files.
Custom GitHub Copilot agents for this repo.
learning-repo-maintainer.agent.md
A GitHub-side maintainer agent focused on structure, learning quality, and consistency.
Optional GitHub Copilot coding agent hook configs.
These files use GitHub's documented .github/hooks/*.json format for Copilot coding agent on GitHub and GitHub Copilot CLI. They are not a general GitHub repository feature and they are not GitHub Actions.
session-start-check.json
An officialsessionStarthook config that runs a small deterministic startup check for core repo guidance files.
Reusable GitHub/Copilot maintainer workflows.
A skill for reviewing pull requests that change the repo's learning structure.
One level deeper:
-
assets/
Reusable review output pieces. -
assets/review-template.md
A template for review findings. -
references/
Supporting docs used during review. -
references/review-checklist.md
A checklist for structure, naming, and correctness. -
scripts/
Helper scripts used by the skill. -
scripts/list-learning-files.sh
Lists learning-related files changed in a PR. -
SKILL.md
The main skill definition and review workflow.
This is the external/shared layer.
Unlike .claude/ and .github/, this layer is mainly for users of the repo and outside agents.
The shared skill for understanding this repository and its layers.
One level deeper:
-
assets/
Reusable user-facing output pieces. -
assets/adoption-plan-template.md
A template for suggesting how to adopt the repo. -
references/
Supporting docs for understanding the repo. -
references/repo-map.md
A simple map of the repo layers and their roles. -
scripts/
Helper scripts for shared usage. -
scripts/quickstart-check.sh
Checks whether the expected starter structure exists. -
SKILL.md
The main shared skill definition.
The shared skill for adopting this repository structure into another project.
One level deeper:
-
assets/
Reusable output pieces for adoption planning. -
assets/adoption-plan-template.md
A template for the final adoption plan. -
references/
Supporting docs for adoption decisions. -
references/repo-map.md
A short summary of the repo layers and what they are for. -
references/adoption-levels.md
Defines minimal, practical, and full adoption levels. -
references/copy-vs-adapt.md
Explains what to copy as-is, adapt, rename, or skip. -
scripts/
Helper scripts for optional adoption checks. -
scripts/quickstart-check.sh
Checks a target repo for a few basic starter files and AI-related paths. -
SKILL.md
The main shared skill definition.
This is the shared technical support layer.
Helper scripts used by hooks.
-
claude-session-context.sh
Emits repo context for Claude session start. -
github-session-start-check.sh
Bash support script for a GitHub Copilot coding agentsessionStarthook.
These scripts are not the lesson itself.
They support the automatic orientation behavior.
Hooks are automatic commands that run at defined lifecycle events.
In this repo, hooks are used for something simple and useful:
- a session starts
- Claude can receive quick orientation context
- GitHub Copilot coding agent can run an optional deterministic startup check
That is a good fit because it is:
- deterministic
- low-risk
- practical
- directly connected to the purpose of the repo
This project shows a few important ideas:
-
AI files should have clear roles
Not everything belongs in one giant instruction file. -
Internal and external AI layers should be separated
Maintainer AI is different from user-facing AI. -
Agents, skills, rules, instructions, and hooks each do different jobs
- rules and instructions = guidance
- agents = specialized roles
- skills = reusable workflows
- hooks = optional deterministic automation for supported runtimes
-
A template repo should still feel real
The best template repos do not only name folders.
They show meaningful files and realistic relationships.
This repo is already in a strong foundation stage.
It already has:
- the root instruction files
- one Claude rule
- one Claude agent
- one Claude skill
- one GitHub instruction set
- one GitHub agent
- one GitHub skill
- two external shared skills
- one optional hook on each side
That means the repo is already more than an idea.
It has a real internal architecture.
ai-repo-structure is a practical learning repository that demonstrates how to structure a real AI-enabled project using shared agent instructions, Claude-specific configuration, GitHub/Copilot-specific configuration, internal maintainer agents and skills, hooks, and external shared skills.