What AI Told Me About How I Work

There’s a particular kind of uncomfortable clarity that comes from asking the tools you use every day to describe you.

I spend most of my working hours inside VS Code Insiders with GitHub Copilot Chat, Copilot CLI, and Claude Code. These agents have seen my repos, my commit patterns, the way I structure instruction files, the questions I ask, and the way I refine answers across multiple passes. So I decided to do something that felt slightly unsettling: I asked them to tell me how I work.

Then I took their observations and cross-referenced them against three recent AI engineering whitepapers to see what concrete improvements the research actually supports. This post is both the mirror and the action plan.

Part 1: The Mirror — What AI Said About My Working Style

Here’s the unedited assessment, synthesized across multiple agents:

---

You tend to write code like an engineer who wants systems to stay understandable under pressure. You seem to prefer starting from a real operational problem, then working backward into tooling, scripts, structure, and guardrails — rather than building abstract demos. Your questions suggest you value fast local workflows, precise control, low overhead, and tools that can be inspected and reasoned about. You also seem biased toward solutions that are practical to run in the real world: native binaries over bloated stacks, deterministic cleanup over magic, and repo structure that helps both humans and agents navigate the codebase.

You appear to leverage AI less like a chatbot user and more like an orchestrator. You use it to compress research, draft plans, inspect architecture, refine prompts and instruction files, extract structured metadata, compare implementation options, and accelerate tedious analysis work. Rather than asking AI to “just build it,” you seem to break work into parts: repo instructions, project context, tools, memory, validation, and workflow design. A recurring pattern in your questions is that you want AI to operate inside a disciplined environment where it can search files, use tools, follow conventions, and avoid wasting context.

Your style is strongly iterative. You often refine an idea through multiple passes: shorten this, make it cleaner, make it more accurate, make it safer, make it faster, make it more maintainable. That suggests your coding approach is not just about producing code, but about shaping the surrounding system so future work gets easier. In practice, you seem to write code and use AI best when the project has a clear structure, explicit instructions, reusable scripts, and a workflow where the model assists with execution while you keep control of architecture, correctness, and final judgment.

---

Reading this back felt like having someone narrate your driving style from the passenger seat. Not wrong. A little too precise. And immediately useful, because it points at what to optimize.

Part 2: What the Research Says to Do Next

With that profile in hand, I reviewed three recent AI engineering papers published in early 2026. Each addresses a different dimension of how developers work with AI coding agents. Below are the six recommendations that directly map to my working style, along with the specific research that supports them.

1. Adopt a Version-Controlled AGENTS.md for “Codified Context”

Since I already break work into repository instructions and project context, the research says to standardize this by placing an AGENTS.md file at the root of every repository.

Recent empirical studies on real-world pull requests reveal that the presence of a root AGENTS.md file reduces an AI coding agent’s median output token consumption by 16.58% and its median wall-clock execution time by 28.64% (Lulla et al., 2026). That’s not a trivial margin — it means the agent spends less time figuring out what you want and more time doing it.

To scale this for complex codebases, the concept of “codified context” (Vasilopoulos, 2026) recommends a two-tier system: a hot-memory AGENTS.md that encodes your core conventions and orchestration protocols, and a cold-memory knowledge base of on-demand specification documents that the agent retrieves only when necessary.

I already have AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md in this site’s repo. The next step is formalizing the hot/cold boundary so the agent isn’t loading everything upfront.

A note on balance: A concurrent 2026 study by Gloaguen et al. found that unnecessarily long context files can sometimes reduce task success and increase costs. The goal is not to write more instructions — it’s to write the right instructions at the right granularity.

2. Leverage File System Navigation over Semantic Search

When using tools for repository-scale reasoning, the agents should use their native terminal proficiency — ripgrep, find, sed, or writing custom Python scripts — rather than relying on standard Retrieval-Augmented Generation (RAG).

Research demonstrates that coding agents perform significantly better when they treat long-context text processing as a hierarchical file system navigation problem (Cao et al., 2026). Instead of passive semantic searches, agents using terminal tools autonomously develop highly effective strategies like iterative query refinement and “indexing and slicing” specific line ranges using coordinate-based reading.

This aligns with something I’ve already noticed in practice: the best agent sessions are the ones where the model greps for what it needs rather than trying to reason over a dump of search results.

3. Enforce Strict Schema Gating During the Planning Phase

I naturally separate work into planning and execution. The research says to make the planning phase safer by strictly filtering the tools available to the AI.

When drafting an architectural plan or exploring a codebase, restrict the agent to a read-only tool schema — file reading, codebase search, and AST matching only. By entirely removing write tools from the agent’s available schema during the planning phase, it becomes structurally impossible for the AI to prematurely modify code while reasoning (Bui, 2026).

This “schema gating” prevents destructive operations and is fundamentally more robust than relying on runtime permission checks or natural-language guardrails. It’s the difference between telling someone “please don’t touch anything” and actually locking the door.

4. Implement Just-In-Time Reminders Instead of Bloated System Prompts

Front-loading all rules into an initial system prompt often fails over long CLI or Chat sessions because the model’s attention drifts away from older instructions as the conversation grows.

Instead of making global prompts larger, inject short, context-aware “system reminders” as role: user messages exactly at the point of decision (Bui, 2026). For example, if you have a workflow rule to run tests before completing a task, injecting a targeted reminder about unchecked tests right before the agent finishes its execution loop drastically improves compliance — because the model assigns higher salience to recent user messages.

This is the kind of insight that changes how you structure agent workflows. It’s not about writing better instructions; it’s about when the model sees them.

5. Offload Large Outputs to Scratch Files to Preserve Context

To prevent context windows from degrading due to massive test logs or build errors, configure the workflow so that any tool output exceeding a certain threshold (e.g., 8,000 characters) is offloaded to a local temporary scratch file (Bui, 2026).

The agent receives only a short preview in its context window along with the path to the scratch file, giving it the autonomy to read the full file explicitly if needed. This effectively turns a massive context-consumption problem into a lightweight retrieval problem.

I’ve hit this exact failure mode multiple times — a long build log fills the context, and the model’s subsequent reasoning degrades. Having a systematic approach to scratch-file offloading is a clear win.

6. Formalize Workload-Optimized Multi-Model Routing

Since I already use different models for different tasks, the research supports formalizing this: strictly map specific models to distinct cognitive phases (Bui, 2026).

• Fast, cheaper models for context compaction and summarization
• Vision-capable models strictly for visual UI debugging
• Extended reasoning models (thinking models) isolated to tool-free planning phases where they can deliberate deeply without being pressured by the availability of action

Providing a separate thinking phase with no tool access produces substantially better reasoning traces, because the model can reason without the temptation to prematurely execute.

What I’m Implementing First

The six recommendations above aren’t equally hard to adopt. My priority order:

1. Hot/cold memory boundary — Restructure my existing instruction files into a clear two-tier system. This is mostly organizational work with an outsized payoff.
2. Just-in-time reminders — Start injecting targeted reminders at decision points in longer agent sessions instead of front-loading more rules.
3. Scratch file offloading — Set a threshold for tool output length and route large results to temp files. This is a workflow configuration change.
4. Schema gating — Explore restricting tool availability during planning phases in my agent configurations.
5. Multi-model routing — Formalize which models handle which cognitive phases instead of ad-hoc switching.
6. File system navigation preference — Already partially doing this; need to make it an explicit instruction in my agent configs.

The Takeaway (First Pass)

Asking your AI tools to describe how you work is a surprisingly effective way to surface patterns you might not articulate yourself. But the real value comes from pairing that self-knowledge with current research. The field of AI-assisted development is moving fast enough that practices from six months ago may already have better alternatives documented in a preprint.

The common thread across all six recommendations is the same principle I keep coming back to: the quality of AI-assisted work depends more on the system around the model than on the model itself. Better context management, smarter tool availability, well-timed instructions, and disciplined routing all compound into workflows where the AI is genuinely useful rather than just fast.

---

Part 3: When the Research Isn’t Specific Enough — A Second Pass

Here’s the part I didn’t expect to write.

After finishing the six recommendations above, I read back through my own article and realized the advice was directionally correct but not specific enough to actually implement. “Restructure into a hot/cold boundary” sounds great in a blog post. But when I sat down to do it, I immediately had questions: which file is hot? What goes in AGENTS.md versus copilot-instructions.md versus CLAUDE.md? Where do custom agents fit? What about skills?

So I did what any self-respecting AI orchestrator would do — I ran my own article back through another AI and asked for specific implementation guidance.

The irony is not lost on me. I wrote an article about iterative refinement, and then the article itself needed iterative refinement. The research gave me the what. I needed another pass to get the how. That’s the gap between a whitepaper and a working system, and it’s worth being honest about.

Here’s what came back.

Give Each File a Narrow Job

The key insight: you don’t pick one of copilot-instructions.md, AGENTS.md, or CLAUDE.md. You use all three, but each one gets a narrow, distinct responsibility.

For VS Code Insiders + GitHub Copilot Chat: .github/copilot-instructions.md is your stable project-wide baseline. AGENTS.md handles agent-facing workflow rules and scoped overrides. Custom .agent.md files are reserved for named workflows you invoke deliberately — things like “planner”, “read-only investigator”, or “ama-log-reviewer.” GitHub’s docs confirm that Copilot agents read AGENTS.md files and the nearest one in the directory tree takes precedence.

For Claude Code: CLAUDE.md serves as the Claude-specific equivalent of your hot memory. Subagents go under .claude/agents/ only where you truly want delegation — a “plan-only architect”, “log triage specialist”, or “docs synthesizer.”

The practical answer to “skills, instructions, or what?” is: use instructions for always-on policy, agent files for workflow specialization, and skills only if the platform supports reusable packaged behavior you can call predictably. The core implementation should not start with skills. It should start with a small instruction stack plus a few sharply-defined agents.

A Clean Repo Layout

repo/
├─ .github/
│  ├─ copilot-instructions.md
│  └─ agents/
│     ├─ planner.agent.md
│     ├─ ama-investigator.agent.md
│     └─ implementation.agent.md
├─ AGENTS.md
├─ CLAUDE.md
├─ docs/
│  ├─ architecture.md
│  ├─ troubleshooting-playbooks.md
│  └─ repo-map.md
└─ tools/
   ├─ scratch/
   └─ prompts/

Split Responsibility Across Files

.github/copilot-instructions.md — the always-on baseline:

• Repository-wide coding standards
• Preferred languages and libraries
• Testing expectations
• Security and secret-handling rules
• “Prefer rg/find/git over semantic search when exploring code”
• “Do not rewrite existing backend unless explicitly asked”

AGENTS.md — how agents should work in this repo:

• Planning vs. implementation protocol
• Read-first rules
• Output format expectations
• Where cold docs live
• What to summarize vs. what to inspect directly
• When to create scratch files for large output

CLAUDE.md — Claude-specific operational memory:

• Important repo commands (test, build, lint)
• Known dangerous paths/files
• Domain terminology
• How to use .claude/agents/*

Example Agent Definitions

Instead of one giant smart agent, create a few very narrow ones.

planner.agent.md — read-only architecture and planning:

You are a read-only planning agent.

Rules:
- Never modify files.
- First build a repo map.
- Prefer rg, git grep, file tree walking, and focused file reads
  over semantic summaries.
- Reference exact files and symbols.
- Identify risks, coupling points, tests, and rollout strategy.
- End with:
  1. findings
  2. proposed plan
  3. files to change
  4. tests to run

implementation.agent.md — scoped changes after a plan exists:

You implement an approved plan.

Rules:
- Do not expand scope.
- Reuse existing backend/core logic.
- Make small diffs.
- Run targeted validation before finishing.
- If output is very large, write it to scratch and summarize.

ama-investigator.md (Claude subagent) — domain specialist:

Focus on:
- log triage
- bundle structure
- known AMA failure patterns
- minimal speculative reasoning
- explicit evidence and file paths

Mapping the Six Recommendations to Real Tooling

Here’s how each research-backed recommendation translates into actual files and workflows:

Hot/cold memory: Keep only stable, short rules in copilot-instructions.md, AGENTS.md, and CLAUDE.md. Put architecture docs, playbooks, repo maps, and domain notes in docs/. The instruction files tell the agent where those docs live and when to open them — not paste them inline.

File system navigation over semantic search: Make it an explicit repo rule. In both Copilot and Claude files: “Prefer rg, git grep, find, targeted file reads, and scripts over broad semantic search for codebase investigation.”

Schema gating: Neither platform gives you perfect hard security boundaries from markdown alone. The practical implementation is to make one agent explicitly read-only (planner) and another explicitly implementation-capable, then only invoke the write-capable one after the plan is accepted. Claude Code subagents are a strong fit here. Copilot custom agents are the closest equivalent.

Just-in-time reminders: Don’t bloat the base files. Keep short reusable prompt snippets in tools/prompts/ and invoke them at the decision point. Example: “Before finalizing: verify tests run, confirm no backend rewrite, summarize changed files only.”

Scratch file offloading: This isn’t something copilot-instructions.md magically enforces — you implement it in workflow. Tell the agent: “If a command output is large, redirect to tools/scratch/<name>.log and only show a compact summary plus the path.” Works especially well in Claude Code and terminal-first flows.

Multi-model routing: Keep it manual and explicit. Planner agent → stronger reasoning model. Implementation agent → faster coding model. UI/visual debugging → vision-capable model. That’s more maintainable than trying to encode hidden routing logic in markdown.

The Condensed Recommendation

If you take one thing from this second pass, it’s this:

1. Keep .github/copilot-instructions.md very short — around one screen.
2. Put repo workflow rules in root AGENTS.md.
3. Keep CLAUDE.md as Claude-specific operational memory.
4. Add 2–4 specialized agents only: planner, implementation, maybe a domain investigator and a log summarizer.
5. Put all heavyweight context in docs/.
6. Add one explicit rule everywhere: prefer terminal/codebase navigation over vague semantic search.
7. Add one explicit rule everywhere: planning is read-only; implementation follows an approved plan.

The research gives you the principles. The second pass gives you the file structure. The gap between those two is where most people stall — and honestly, where I almost stalled too.

---

Part 4: The Corrections — Because Apparently Three Passes Isn’t Enough

At this point you’re probably sensing a pattern. Write something. Refine it. Discover it’s still wrong. Refine again.

I took Part 3’s implementation guidance and fact-checked it against the actual VS Code Copilot Customization docs, GitHub’s official custom instructions documentation, and GitHub’s custom agents docs. The irony of needing a third refinement pass on an article partly about iterative refinement is genuinely funny to me now.

Here’s what the AI got wrong — or at least got imprecise enough to be misleading.

Correction 1: AGENTS.md Is Not “Agent-Facing Workflow Rules”

Part 3 framed AGENTS.md as the place for agent-specific workflow rules, distinct from copilot-instructions.md which handles “project-wide baseline” standards. That framing implies they serve fundamentally different audiences.

What the docs actually say: Both copilot-instructions.md and AGENTS.md are classified as always-on instructions that automatically apply to all chat requests in the workspace. The VS Code docs list them side by side in the same category. The difference is organizational, not functional — AGENTS.md is described as “useful if you work with multiple AI agents in your workspace” and supports subfolder scoping (experimental), but it’s not a separate runtime system. Both files feed into every chat request.

The nearest-in-directory-tree precedence for AGENTS.md is real — GitHub’s docs confirm that. But the Part 3 framing of “copilot-instructions for humans, AGENTS.md for agents” overstates the architectural boundary.

Correction 2: Skills Are Real and You Shouldn’t Dismiss Them

Part 3 said: “The core implementation should not start with skills. It should start with a small instruction stack plus a few sharply-defined agents.”

That’s debatable advice presented as fact. VS Code has supported Agent Skills since version 1.108 (December 2025). Skills live in .github/skills/ as folders containing a SKILL.md file plus supporting scripts and resources. They use progressive disclosure — Copilot reads only the skill metadata until the skill is invoked, keeping context budget low. They surface as slash commands in chat and are available across VS Code, Copilot CLI, and the Copilot coding agent.

Skills aren’t some speculative feature you might use someday — they’re a shipping, documented extensibility layer with an open standard and a community repository of implementations. The progressive disclosure model actually aligns perfectly with the hot/cold memory split from the whitepapers: skill metadata is hot, skill scripts and templates are cold.

Correction 3: Missing — Path-Specific .instructions.md Files

Part 3’s repo layout includes copilot-instructions.md, AGENTS.md, and .agent.md files. It completely omits path-specific instructions: *.instructions.md files that live in .github/instructions/ and conditionally apply based on applyTo glob patterns.

This is actually one of the most useful customization features because it lets you scope rules to file types:

---
applyTo: "**/*.ts,**/*.tsx"
---
# TypeScript conventions
- Use strict mode
- Prefer interfaces over type aliases for object shapes

The precedence order matters too: Personal instructions > Path-specific instructions > Repository-wide copilot-instructions.md > Agent instructions (AGENTS.md). If you’re designing a layered instruction system and you skip .instructions.md files, you’re missing the middle layer.

Correction 4: Those Agent Tool Names Are Wrong

Part 3’s example planner.agent.md specifies:

tools: read, search, grep, glob

Those aren’t actual VS Code tool names. VS Code custom agents use tools as an array of real tool identifiers — things like editFiles, runInTerminal, codebase, and specific MCP server tool names. The docs explicitly warn: “Tool names vary across GitHub Copilot platforms. Check the tools available in your specific IDE.” You can see available tool names by selecting the Tools icon in the Copilot Chat window.

A more accurate planner agent would either omit the tools property (all tools enabled by default) or use actual VS Code tool identifiers to restrict capabilities.

Correction 5: CLAUDE.md Is Recognized by VS Code, Not Just Claude Code

Part 3 frames CLAUDE.md as a Claude Code-specific file. But the VS Code docs now list CLAUDE.md alongside AGENTS.md as a recognized always-on instructions file in VS Code itself. So if you have a CLAUDE.md in your workspace, VS Code Copilot will pick it up too — it’s not siloed to Claude Code anymore.

This is worth knowing because it means your “Claude-specific operational memory” might be leaking into Copilot sessions. Whether that’s desirable depends on how divergent your Claude and Copilot instructions are.

The Corrected Mental Model

After three passes and a documentation review, here’s the actual layered system as it exists today:

Layer	File	Scope	When Applied
Always-on (global)	.github/copilot-instructions.md	All chat requests	Automatic
Always-on (multi-agent)	AGENTS.md (root or subfolder)	All chat requests	Automatic, nearest wins
Always-on (model-specific)	CLAUDE.md, GEMINI.md	All chat requests	Automatic
Path-specific	.github/instructions/*.instructions.md	Matching file patterns	Automatic via applyTo
Custom agents	.github/agents/*.agent.md	When invoked by name	Manual selection
Skills	.github/skills/*/SKILL.md	When relevant to task	Progressive disclosure
Prompt files	.github/prompts/*.prompt.md	When invoked	Manual / command

What This Whole Exercise Actually Proved

I started this article by asking AI to describe how I work. It said I’m “strongly iterative” and that I “refine an idea through multiple passes.” I did not expect the article itself to become a four-pass demonstration of that exact pattern:

• Pass 1: Research synthesis. Directionally correct, not specific enough.
• Pass 2: Implementation guidance. More specific, but partly hallucinated.
• Pass 3: Fact-check against actual documentation. Found real errors.

If you’re building AI-assisted workflows, this is the thing to internalize: the model is confident at every pass. Pass 2 presented incorrect tool names and a misleading AGENTS.md framing with the same authoritative tone as the parts it got right. The only thing that caught the errors was going to the source documentation — which, fittingly, is exactly what the whitepapers recommended in the first place (prefer direct file navigation over trusting summarized search results).

The AI was right about how I work. It just took me four passes to prove it.

---

Part 5: The Tool-Switching Problem Nobody Warned Me About — A Fifth Pass

Yes. Five passes. At this point the iterative refinement has become the joke and the lesson.

After publishing the four-part version of this article, I realized there’s a fundamental blind spot I never addressed: I don’t use one tool. I use three — GitHub Copilot Chat in VS Code, GitHub Copilot CLI (including the coding agent), and Claude Code in the terminal — and I switch between them constantly, sometimes within the same hour, always within the same repo. Each one reads a different subset of my instruction files. Each one has its own agent system. And I’d been writing about “my instruction stack” as if it were one coherent thing, when in reality it’s three overlapping systems with different rules, different file hierarchies, and different blind spots.

This is the part I should have written first. But I didn’t see it clearly until the blog-author agent I built for this site — the one that literally wrote parts of this article — forced the question: which tool is even reading which file right now?

Three Tools, Three Instruction Models

Here’s what actually happens when you have copilot-instructions.md, AGENTS.md, and CLAUDE.md in the same repo:

GitHub Copilot Chat (VS Code) reads all three. The VS Code Copilot Customization docs list copilot-instructions.md, AGENTS.md, and CLAUDE.md as always-on instruction sources. It also picks up path-specific .instructions.md files from .github/instructions/, custom agents from .github/agents/, and skills from .github/skills/. The precedence order is: personal instructions > path-specific instructions > copilot-instructions.md > agent instructions (AGENTS.md, CLAUDE.md).

GitHub Copilot CLI / Coding Agent reads copilot-instructions.md and path-specific .instructions.md files. The GitHub docs confirm it also recognizes AGENTS.md. But it operates in the terminal or as a remote agent opening PRs — it does not have the same custom agent invocation model as VS Code Chat. You can’t @blog-author from the CLI.

Claude Code reads CLAUDE.md files hierarchically — from your working directory up to the root, discovering nested ones in subdirectories as it accesses files. It also reads its own user-level ~/.claude/CLAUDE.md for personal preferences and ~/.claude/agents/ for user-scoped subagents. Project subagents live in .claude/agents/. Claude Code does not read copilot-instructions.md, .github/agents/*.agent.md, or .github/skills/. It has its own skill system using .claude/skills/ with a different frontmatter format.

So when I switch from Copilot Chat to Claude Code in this repo, the agent goes from seeing my blog-author agent, my site-reviewer agent, my new-blog-post skill, and all three instruction files — to seeing only CLAUDE.md and whatever’s in .claude/. That’s a completely different context surface.

The Real Repo Has Multiple Agents — And They Don’t Port

This site’s repo has three custom Copilot agents in .github/agents/:

• blog-author.md — writes blog posts with correct frontmatter, tone, and file placement
• rust-log-author.md — creates Rust learning log entries with logKey ordering
• site-reviewer.md — reviews code changes against styling, SEO, and content standards

And four skills in .github/skills/:

• new-blog-post.md — scaffolds a new blog post
• new-rust-log.md — scaffolds a Rust log entry
• new-component.md — scaffolds an Astro component
• update-seo.md — updates SEO metadata

These are Copilot-specific. If I open Claude Code in this same repo and say “write me a blog post,” it has no idea about my blog-author agent’s conventions unless I’ve duplicated those instructions into CLAUDE.md or .claude/agents/. And Claude Code’s subagent system works differently — subagents are Markdown files with YAML frontmatter that specify custom prompts and tool access, and they run in isolated context windows.

This is the tool-switching tax nobody talks about. You’re not maintaining one set of instructions. You’re maintaining parallel instruction surfaces that partially overlap on the shared files (CLAUDE.md, AGENTS.md) and completely diverge on agent definitions, skills, and tool-specific configuration.

What Actually Gets Shared vs. What Diverges

Feature	Copilot Chat (VS Code)	Copilot CLI / Coding Agent	Claude Code
copilot-instructions.md	✅ Always-on	✅ Always-on	❌ Not read
AGENTS.md	✅ Always-on	✅ Always-on	❌ Not read
CLAUDE.md	✅ Always-on	❌ Not documented	✅ Always-on (hierarchical)
Path-specific .instructions.md	✅ Via applyTo globs	✅ Via applyTo globs	❌ Not read
Custom agents	.github/agents/*.agent.md	❌ Not invocable	.claude/agents/*.md
Skills	.github/skills/*/SKILL.md	✅ Available	.claude/skills/ (different format)
User-level instructions	VS Code settings	N/A	~/.claude/CLAUDE.md
Memory	Copilot memory system	N/A	Auto-memory + CLAUDE.md

The practical implication: copilot-instructions.md and AGENTS.md are your Copilot-side baseline. CLAUDE.md is your Claude-side baseline. Neither side sees the other’s agents or skills. The only instruction files with cross-tool visibility are AGENTS.md and CLAUDE.md in Copilot Chat — but that’s one-directional, since Claude Code doesn’t read AGENTS.md.

Designing for Multi-Tool Reality

After staring at this table long enough, three strategies emerged:

1. Keep the shared files focused on universal truths. AGENTS.md and CLAUDE.md in this repo contain the same core content: build commands, architecture overview, content collection structure, conventions. That’s intentional — both files describe the project, not the tool. Any instruction that’s tool-specific (like “use rg over semantic search” in Claude Code, or “prefer the codebase tool” in Copilot) belongs in tool-specific configuration, not the shared baseline.

2. Accept the duplication tax for agents. If your blog-author agent matters in both tools, you need it defined in both .github/agents/blog-author.md (for Copilot) and .claude/agents/blog-author.md (for Claude Code). The formats are different — Copilot uses name/description/tools YAML frontmatter with markdown body instructions, while Claude Code uses name/description/model/allowedTools frontmatter. You can keep the prose instructions identical and parameterize the metadata. It’s not elegant, but it’s honest.

3. Use skills for progressive disclosure, not as a substitute for agents. In Copilot, skills load their metadata into context but keep the heavy implementation cold until invoked — that maps perfectly to the hot/cold memory pattern from the whitepapers. Claude Code’s skill system works similarly but uses .claude/skills/ with @import syntax for pulling in files. The key insight from the VS Code docs: skills surface as tool calls available to agents, while agents are personalities you invoke. Don’t conflate them. An agent is who’s working. A skill is what they can do.

The Corrected Mental Model (For Real This Time)

The table from Part 4 was accurate for Copilot Chat in isolation. Here’s the multi-tool version:

For GitHub Copilot (Chat + CLI + Coding Agent):

Layer	File	Loaded
Always-on	.github/copilot-instructions.md	Auto
Always-on	AGENTS.md	Auto
Always-on	CLAUDE.md	Auto (VS Code only)
Path-scoped	.github/instructions/*.instructions.md	Auto via applyTo
Named agents	.github/agents/*.agent.md	On invocation
Skills	.github/skills/*/SKILL.md	Progressive disclosure
Prompts	.github/prompts/*.prompt.md	Manual / command

For Claude Code:

Layer	File	Loaded
Managed policy	System-level CLAUDE.md	Auto
Project instructions	./CLAUDE.md or ./.claude/CLAUDE.md	Auto at session start
User instructions	~/.claude/CLAUDE.md	Auto
Subagents	.claude/agents/*.md	On delegation
Skills	.claude/skills/	On invocation
Imports	@file references in CLAUDE.md	On session start

These are two different architecture diagrams that happen to share some input files. Treating them as one system is how you end up with agents that work perfectly in Copilot Chat and do nothing in Claude Code — or worse, CLAUDE.md instructions leaking into Copilot sessions in ways you didn’t intend.

What This Finally Taught Me

Five passes. Each one caught something the previous pass missed. And the final lesson is maybe the most practical one in the entire article:

If you use multiple AI coding tools in the same repo, your instruction system is not a stack — it’s a Venn diagram. The overlap is your project knowledge (architecture, conventions, build commands). The non-overlapping parts are tool-specific agents, skills, memory systems, and configuration. Designing for this means:

1. Put project truths in files that both tools read (CLAUDE.md for universal, AGENTS.md for Copilot-side).
2. Accept that agent definitions need per-tool implementations.
3. Keep CLAUDE.md under ~500 lines (per Anthropic’s recommendation) and move reference material to skills or docs.
4. Don’t assume a feature that works beautifully in one tool exists at all in another.
5. Test your instruction setup from each tool’s perspective, not just your favorite one.

And maybe most importantly: if you’re writing a blog post about AI-assisted workflows and you use an AI agent to write it, the agent itself becomes both the subject and the demonstration. This article was drafted and refined across Copilot Chat using a custom blog-author agent, fact-checked through Claude Code, and validated against live documentation via MCP. The fact that those three tools needed different instruction contexts to do their parts of the job is the whole point.

The AI was right about how I work. It just took five passes — and switching between three different AI tools — to fully prove it.

---

References

1. Lulla, J. L., Mohsenimofidi, S., Galster, M., Zhang, J. M., Baltes, S., & Treude, C. (2026). On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents. Proceedings of Journal Ahead Workshop (JAWs) 2026. arXiv:2601.20404

2. Vasilopoulos, A. (2026). Codified Context: Infrastructure for AI Agents in a Complex Codebase. arXiv preprint arXiv:2602.20478. arXiv:2602.20478

3. Cao, W., Yin, X., Dhingra, B., & Zhou, S. (2026). Coding Agents are Effective Long-Context Processors. arXiv preprint arXiv:2603.20432. arXiv:2603.20432

4. Bui, N. D. Q. (2026). Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned. arXiv preprint arXiv:2603.05344. arXiv:2603.05344

5. Gloaguen, T., et al. (2026). [On the impact of context files on AI coding agents]. arXiv preprint arXiv:2602.11988. arXiv:2602.11988