Custom Instructions for AI Coding Agents Without Duplication

Custom instructions give AI coding agents persistent repository context, but there is no single file layout shared by every tool. GitHub Copilot, OpenAI Codex, and Claude Code each document different discovery paths. Our practice is to keep one detailed source of truth, use thin vendor entrypoints, and reserve skills for task-specific procedures.

Why “Put It in .github/” Is Incomplete Advice

For GitHub Copilot, .github/ is central. For Codex, the documented repository instruction file is AGENTS.md. For Claude Code, the project entrypoint is CLAUDE.md or .claude/CLAUDE.md.

All three can participate in the same repository, but only if the team distinguishes:

• documented vendor behavior;
• the repository’s chosen compatibility architecture;
• task-specific skills;
• controls that must be enforced in code or CI.

This article describes the layout we use in the StartMeUpAI website and the ByblosAI application. It is a practical convention, not a new cross-vendor standard.

The Vendor Behaviors

The following table summarizes the documented project-level mechanisms at the time of writing:

Vendor support varies by product surface and version. For example, GitHub documents that path-specific instructions are not supported identically across every IDE and Copilot feature. Treat the vendor documentation as the source of truth, not a diagram copied into a blog post years earlier.

Our Repository Convention

We organize guidance by purpose:

AGENTS.md
CLAUDE.md
.github/
├── AGENTS.md
├── copilot-instructions.md
├── agents/
├── instructions/
└── skills/

This is our convention:

• Root AGENTS.md is the main entrypoint for AGENTS-aware tools.
• Root CLAUDE.md gives Claude Code a native entrypoint.
• .github/copilot-instructions.md gives Copilot its repository context.
• .github/AGENTS.md contains the detailed catalog and validation guidance.
• .github/instructions/ contains path-scoped Copilot rules.
• .github/skills/ is our procedural source of truth.

The root files are intentionally thin. They point to detailed guidance instead of copying it. This gives each tool a native place to start while keeping the substantive rules maintainable.

Native skill discovery is a separate concern. If a runtime only auto-discovers .agents/skills or .claude/skills, a pointer in an instruction file is not identical to native discovery. Teams can use supported directories, adapters, packaging, or an explicit “read this skill” workflow. They should test the chosen arrangement in every tool they claim to support.

What Belongs in Persistent Instructions

Good persistent instructions describe facts and constraints that apply across many tasks:

• package-manager commands;
• architecture boundaries;
• file-placement rules;
• naming and import conventions;
• reusable components and patterns;
• required validation;
• security and authorization principles;
• reporting expectations.

Our ByblosAI repository, for example, tells agents to use pnpm, keep strict TypeScript, avoid barrel re-exports, keep database work in the database layer, reuse shared primitives, and preserve a one-way shared-tier dependency graph.

Those are repository facts. An agent editing a page, API, test, or document may need them.

What Does Not Belong There

Persistent instructions become less useful when they turn into a manual for every possible task.

Move guidance into a skill when it contains:

• a multi-step workflow for one task;
• task-specific tools or scripts;
• an artifact template;
• detailed examples;
• a specialized validation sequence;
• a procedure that should load only when relevant.

For example, “run pnpm typecheck before completion” can be a repository instruction. The complete browser-investigation procedure—including server setup, authentication, screenshots, console capture, and regression evidence—belongs in a browser-testing skill.

Path-Scoped Instructions in GitHub Copilot

GitHub Copilot supports files named NAME.instructions.md under .github/instructions/. The applyTo frontmatter selects matching paths:

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

# Content Instructions

- Do not add an H1; the title comes from frontmatter.
- Verify factual claims against primary sources.
- Add internal links that resolve at publication time.

This mechanism is documented GitHub behavior. It should not be described as a generic Markdown or Agent Skills feature.

Our recommendation is to keep scopes narrow enough to avoid irrelevant context and broad enough to match the real tree. Test the glob against actual files. A perfectly written instruction with a non-matching scope is operationally absent.

Nested Instructions in Codex and Claude

Codex documents AGENTS.md files at repository and nested-directory levels. Claude Code similarly supports project instructions and more specific instruction files as work moves through the tree.

This creates a useful monorepo pattern:

AGENTS.md
packages/
├── billing/
│   └── AGENTS.md
└── analytics/
    └── AGENTS.md

The root explains company-wide defaults. The nested file explains local architecture and validation. Do not repeat the entire root file in each package. Add only the guidance that is more specific.

The One-Source-of-Truth Rule

We use the following decision:

Thin references are healthy:

For plan execution, use the plan-operations skill and keep its checklist truthful.

Full copied procedures are not:

For plan execution, here are the same 60 steps already maintained in SKILL.md...

When a detail appears in several places, decide which file owns it and make the others link or summarize.

How We Handle Conflicts

Instruction systems can combine organization, user, repository, nested, persona, skill, and prompt context. Conflicts are therefore possible even with a clean directory.

Our conflict review asks:

1. Which instruction is documented to have precedence in this runtime?
2. Which file is the repository’s declared source of truth?
3. Is one copy stale?
4. Is the conflict behavioral guidance or a control that should be enforced technically?
5. Can the lower-level file be reduced to a reference?

Do not assume the model will always infer the desired priority. Remove contradictory guidance.

An Example From Our Working Style

Our repositories distinguish automated evidence from live evidence:

• Unit tests can prove a function behaves under tested inputs.
• Type checking can prove declared types are consistent.
• A build can prove the application compiles for its target.
• None of those automatically proves a signed-in browser flow, an external provider, or a production deployment.

We keep that principle in repository guidance because it applies broadly. Individual skills then define the exact evidence required for browser testing, provider verification, or release sign-off.

This is our practice based on repeated delivery work. It is not a feature guaranteed by any agent runtime.

A Migration Plan for Duplicated Instructions

If your repository already has several overlapping files:

1. Inventory every persistent instruction, agent brief, and skill.
2. Group repeated rules by meaning.
3. Choose one primary owner for each detailed rule.
4. Replace copies with short references.
5. Add vendor-native entrypoints without copying the full content.
6. Test which files actually load in each supported tool.
7. Add technical enforcement for critical invariants.
8. Review the result after the next real task, not only in a static audit.

Key Takeaways

1. Copilot, Codex, and Claude use different documented instruction paths.
2. .github/instructions and applyTo are GitHub Copilot mechanisms, not universal standards.
3. Our convention uses thin native entrypoints and one detailed source of truth.
4. Persistent instructions hold durable repository constraints; skills hold task procedures.
5. Critical guarantees belong in code, authorization, schemas, or CI.

Frequently Asked Questions

Should every repository have AGENTS.md, CLAUDE.md, and Copilot instructions?

Only if the team supports those tools and needs native entrypoints. Adding files without a maintenance plan creates more drift. Start with the tools you actually use.

Can CLAUDE.md point to AGENTS.md?

Claude Code documents importing an existing AGENTS.md from CLAUDE.md, which can reduce duplication. Confirm the syntax and loading behavior against the current Claude documentation.

Does an instruction file enforce a rule?

No. It guides model behavior. Use permissions, code, schema validation, lint rules, tests, hooks, or CI for requirements that must be enforced.

Where should build and test commands live?

Keep the canonical commands in repository-level instructions or developer documentation. Skills can reference them and add task-specific sequencing without redefining the commands.

Official References

• GitHub Copilot repository custom instructions
• GitHub Copilot instruction support matrix
• OpenAI Codex customization
• Claude Code project memory and instructions

Conclusion

The goal is not to force every agent into the same folder tree. The goal is to give each tool an accurate entrypoint while maintaining one coherent repository model.

That is why we describe .github/, AGENTS.md, and CLAUDE.md as compatibility choices backed by our experience. They are valuable conventions, but the vendor documentation remains authoritative for discovery behavior.

For the neighboring design problem, read Agent Personas vs. Skills and How to Write Agent Skills That Work Reliably. For our broader delivery perspective, see External Developer Standards for Agentic Software Development.

Want a repository that can guide several AI coding tools without contradictory copies? Explore ByblosAI or contact us.