How to Structure .github/ for AI Coding Agents

Structure your .github/ directory around three folders: skills/ for on-demand procedural capabilities, agents/ for persona definitions, and instructions/ for always-on project rules. Each skill is its own folder with a SKILL.md; each agent is a single persona file; each instruction file scopes its rules with applyTo. Keeping these in separate lanes is what makes an agent-ready repository discoverable and portable.

Introduction

In the first article of this series we defined what an Agent Skill is. Now we zoom out to the whole directory. A messy .github/ is not just untidy — it actively degrades agent behavior, because the agent cannot reliably find the right rule at the right time.

This article gives you the canonical layout and the boundaries that make it work.

The Canonical Layout

Here is the shape an agent-ready repository should have:

.github/
├── copilot-instructions.md          # Optional: repo-wide default instructions
├── agents/
│   ├── blog-agent.md                # Persona: role, boundaries, which skills to use
│   └── performance-agent.md
├── instructions/
│   ├── content.instructions.md      # Scoped rules (applyTo: src/content/**/*.md)
│   └── markdown.instructions.md
└── skills/
    ├── blog-post/
    │   └── SKILL.md                 # One folder per skill
    ├── image-optimization/
    │   └── SKILL.md
    └── xeo-optimization/
        └── SKILL.md

Three directories, three jobs. The moment you can look at a path and know what kind of guidance lives there, both humans and agents move faster.

The Three Lanes

1. skills/ — procedural capabilities, loaded on demand

Every skill is a folder named for the skill, containing exactly one SKILL.md. The folder name is the skill’s identity; the file carries name/description frontmatter and a body of steps, templates, and examples.

The rule of thumb: if it is a task you perform repeatedly with a defined procedure, it is a skill. Writing a blog post, optimizing an image, or running a dependency upgrade all qualify.

2. agents/ — personas, not procedures

An agent file defines who is doing the work: their role, domain expertise, boundaries, and which skills they should reach for. It should read like a job description, not a runbook.

## Skills to Use

- [blog-post](../skills/blog-post/SKILL.md)
- [xeo-optimization](../skills/xeo-optimization/SKILL.md)

A persona references skills conceptually — “use the blog-post skill to draft the article” — but does not inline the procedure. We devote a whole article later in this series to keeping personas and skills apart, because collapsing them is the most common failure mode.

3. instructions/ — always-on, scoped rules

Instruction files hold project-wide standards: coding conventions, formatting rules, structural expectations. What makes them powerful is scoping. An instruction file can declare where it applies:

---
applyTo: 'src/content/**/*.md'
---

# Content Instructions

Every blog post MUST have valid frontmatter...

That applyTo glob means the rules activate only for matching files. A well-scoped instruction set never bothers the agent with Markdown rules while it edits TypeScript.

The One Rule That Prevents Most Problems

No duplication across lanes. The single most common structural defect is the same logic appearing in an instruction and a skill and a persona. When three sources say slightly different things, the agent has no way to know which wins.

Give every rule exactly one home:

• Broad standard that always applies? → instructions/
• Step-by-step procedure for a specific task? → skills/
• Role, boundaries, and skill references? → agents/

A Quick Self-Check

Run this checklist against your own repository:

• Does .github/skills/ exist, with one folder per skill?
• Does each skill folder contain exactly one SKILL.md?
• Does every SKILL.md have name and description frontmatter?
• Are agent files in .github/agents/ free of step-by-step procedures?
• Do instruction files use applyTo scopes that match real project paths?
• Is any single rule defined in more than one place?

If you answer “no” to the first four or “yes” to the last, you have structural work to do. We turn this checklist into a full readiness scorecard later in the series.

Key Takeaways

1. Use three folders: skills/ (procedures), agents/ (personas), instructions/ (always-on rules).
2. Each skill is its own folder with exactly one SKILL.md carrying name/description frontmatter.
3. Personas reference skills but never inline their procedures.
4. Instruction files scope with applyTo globs that match real paths — and no rule lives in two lanes at once.

Frequently Asked Questions

Where should Agent Skills go in a repository?

Skills belong in .github/skills/, with one folder per skill and a single SKILL.md inside each. The folder name identifies the skill, and the SKILL.md holds its metadata and instructions.

What is the difference between the agents, instructions, and skills folders?

agents/ holds persona definitions (role and boundaries), instructions/ holds always-on project-wide rules that can be scoped with applyTo, and skills/ holds task-specific procedures loaded on demand. Each lane has one job, and logic should not be duplicated across them.

What is applyTo in an instruction file?

applyTo is a glob pattern in an instruction file’s frontmatter that limits where the rules apply, for example src/content/**/*.md. It ensures the agent only sees relevant standards for the files it is actually editing.

Can I use copilot-instructions.md and the instructions folder together?

Yes. copilot-instructions.md typically holds repo-wide defaults, while files in .github/instructions/ hold scoped rules for specific paths. Use the folder for anything that should apply to only part of the codebase, and avoid repeating the same rule in both.

Conclusion

A disciplined .github/ layout is the foundation everything else in this series builds on. Three lanes, clear boundaries, no duplication — that is what lets an agent find the right guidance at the right moment.

Next, we go deep on the skills lane: how to write a SKILL.md that agents actually select and follow.

Want this structure delivered with your codebase, not bolted on later? See how our AI agents redefine delivery standards, explore the ByblosAI platform, or contact us.

Related reading: What Are Agent Skills? The Open SKILL.md Standard Explained