Copilot Workspace does not read AGENTS.md or CLAUDE.md. That’s the short answer — but the full picture is more nuanced, because Copilot Workspace does read .github/copilot-instructions.md, and there are practical patterns for keeping that file in sync with the AGENTS.md your other tools use. We tested all three configuration files across a multi-tool repository and documented exactly what Copilot Workspace picks up, what it ignores, and how to structure your repo when you’re running Copilot Workspace alongside Claude Code or Cursor.
Browse our rules gallery to see real examples of AGENTS.md, CLAUDE.md, and copilot-instructions.md files used in production.
What GitHub Copilot Workspace Actually Reads
Copilot Workspace is GitHub’s task-based AI coding environment, separate from the Copilot Chat panel in your editor. It reads only one configuration file:
.github/copilot-instructions.md — GitHub’s official custom instructions file for the Copilot product family. Copilot Workspace, Copilot Chat (in VS Code and JetBrains), and Copilot code review all load this file.
| File | Copilot Workspace | Copilot Chat (IDE) | Copilot CLI |
|---|---|---|---|
.github/copilot-instructions.md | ✅ Read | ✅ Read | ❌ Not read |
AGENTS.md | ❌ Not read | ❌ Not read | ❌ Not read |
CLAUDE.md | ❌ Not read | ❌ Not read | ❌ Not read |
.cursorrules | ❌ Not read | ❌ Not read | ❌ Not read |
Copilot Workspace has no built-in mechanism to load arbitrary markdown files as instructions. It uses the .github/copilot-instructions.md path exclusively.
This creates a coordination problem for teams that use multiple AI tools on the same repository: the instructions you maintain for Claude Code, Codex CLI, or Cursor live in different files, and there’s no native merge or include mechanism across tools.
AGENTS.md vs copilot-instructions.md: Key Differences
AGENTS.md and .github/copilot-instructions.md serve the same purpose — providing persistent context to an AI agent — but they target different tools and have different conventions.
| Dimension | AGENTS.md | .github/copilot-instructions.md |
|---|---|---|
| Primary consumer | Claude Code, OpenAI Codex CLI, Aider, Continue | Copilot Workspace, Copilot Chat |
| Location | Project root (or any directory in a hierarchy) | Must be exactly .github/copilot-instructions.md |
| Hierarchy support | Yes — nested AGENTS.md files compose | No — single file, no hierarchy |
| Format | Markdown, any structure | Markdown, any structure |
| Size limit | No documented limit | GitHub recommends under 8,000 characters |
| Read by Cursor | No (Cursor uses .cursorrules / .mdc) | No |
| Read by Copilot Workspace | No | Yes |
| Access control | Git permissions | Git permissions + GitHub org policy |
| Schema validation | None | None |
The key structural difference: AGENTS.md supports hierarchical composition. You can have an AGENTS.md in the repo root for global rules and additional AGENTS.md files in subdirectories for package-specific rules. Claude Code and Codex CLI merge these automatically. Copilot Workspace has no equivalent — it reads one file only.
Setting Up copilot-instructions.md for Maximum Effectiveness
A well-structured .github/copilot-instructions.md follows the same principles as a good AGENTS.md: clear sections, explicit rules rather than suggestions, and concrete examples.
# Copilot Instructions
## Project Overview
This is a TypeScript monorepo (pnpm workspaces) with a Next.js frontend (`apps/web`),
an Express API (`apps/api`), and shared packages (`packages/`).
## Code Style
- TypeScript strict mode everywhere. No `any` without a comment explaining why.
- Prefer named exports over default exports.
- Use absolute imports via `@repo/` path aliases, not relative `../../` chains.
- No `console.log` in production code — use the `logger` utility from `@repo/logger`.
## Testing
- Every new function in `packages/` requires a unit test.
- Integration tests go in `apps/*/tests/integration/`.
- Use `vitest` for unit tests and `playwright` for E2E.
- Test file naming: `{name}.test.ts` adjacent to the source file.
## Database
- Never call the database directly from route handlers. Use the repository pattern in `packages/db/`.
- All schema changes require a migration file in `packages/db/migrations/`.
- Timestamps use UTC. No local timezone conversions in the database layer.
## Git
- Commit messages: `{type}({scope}): {description}` — conventional commits format.
- PR titles must be `{type}({scope}): {description}` to pass CI.
- No `--force` push to `main` or `develop`.
## Security
- No secrets in source code. Use environment variables defined in `.env.example`.
- User input must be validated with Zod before reaching business logic.
- SQL queries use parameterized statements only — no string interpolation.We found three things consistently matter for Copilot Workspace effectiveness:
-
Put the most important rules first. Copilot Workspace doesn’t guarantee equal attention to all sections. Rules at the top get applied more reliably in our testing.
-
Use imperative language. “Never call the database directly” outperforms “It’s best to avoid calling the database directly”. Copilot Workspace responds to explicit prohibitions better than suggestions.
-
Include the tech stack explicitly. Workspace generates tasks based on file analysis, but explicit stack declarations in the instructions file prevent wrong framework assumptions.
Using AGENTS.md Alongside copilot-instructions.md (The Reference Pattern)
Since Copilot Workspace only reads .github/copilot-instructions.md and other tools only read AGENTS.md, you have two options for a multi-tool repo:
Option A: Maintain two separate files (simple, diverges over time)
Write .github/copilot-instructions.md for Copilot and AGENTS.md for Claude Code / Codex. Accept that they’ll diverge and review both during sprint retrospectives.
Option B: Use AGENTS.md as the source of truth (recommended for active repos)
Keep the full rule set in AGENTS.md, then make .github/copilot-instructions.md reference it:
# Copilot Instructions
<!-- This file is a summary for GitHub Copilot. Full rules: AGENTS.md -->
## Project: TypeScript monorepo (pnpm workspaces)
- Next.js frontend · Express API · shared packages
- Strict TypeScript · named exports · @repo/ path aliases
- Vitest unit tests · Playwright E2E
- Conventional commits · Zod validation on all user input
- No secrets in code — ENV vars only
- No direct DB calls from route handlers — use repository pattern
For extended rules, context, and examples, see AGENTS.md in the repo root.This approach works because:
.github/copilot-instructions.mdstays concise and within the 8,000 character recommendationAGENTS.mdholds the authoritative, detailed version- Humans and Claude Code / Codex CLI use AGENTS.md; Copilot Workspace gets the summary
- When rules change, you update AGENTS.md first, then sync the summary
The reference to AGENTS.md in the Copilot instructions has no functional effect on Workspace — Copilot doesn’t follow the reference and load AGENTS.md. But it communicates to team members which file to edit when rules need updating.
Team Setup: Copilot Workspace + Claude Code + Cursor in One Repo
Many teams now run multiple AI tools on a single repository. Here’s the file structure that covers all three:
repo-root/
├── .github/
│ └── copilot-instructions.md ← Copilot Workspace + Copilot Chat
├── AGENTS.md ← Claude Code + OpenAI Codex CLI + Aider
├── CLAUDE.md ← Claude Code only (overrides AGENTS.md for CC)
├── .cursor/
│ └── rules/
│ └── main.mdc ← Cursor (.mdc format, replaces .cursorrules)
└── ...What each tool reads:
- Copilot Workspace:
.github/copilot-instructions.mdonly - Claude Code:
CLAUDE.md(takes priority), thenAGENTS.mdas fallback - OpenAI Codex CLI:
AGENTS.mdonly - Cursor:
.cursor/rules/*.mdcfiles (newer format) or.cursorrules(legacy) - Aider:
AGENTS.md(loaded as context)
Maintenance strategy:
AGENTS.mdis the base truth — covers rules all agents should followCLAUDE.mdextends or overrides for Claude Code-specific behavior (hooks, sub-agent patterns, permission settings).github/copilot-instructions.mdis a curated summary of AGENTS.md for Copilot.cursor/rules/main.mdcis a Cursor-adapted version (Cursor’s glob-based rule activation differs from AGENTS.md)
During code review, we enforce a rule: if you change AGENTS.md, you must update the summary in .github/copilot-instructions.md before the PR can merge. A pre-push hook that checks file modification timestamps handles this automatically:
#!/bin/bash
# .git/hooks/pre-push
AGENTS_MODIFIED=$(git diff --name-only HEAD~1 | grep -c "^AGENTS.md$")
COPILOT_MODIFIED=$(git diff --name-only HEAD~1 | grep -c "^.github/copilot-instructions.md$")
if [ "$AGENTS_MODIFIED" -gt 0 ] && [ "$COPILOT_MODIFIED" -eq 0 ]; then
echo "AGENTS.md changed but .github/copilot-instructions.md was not updated."
echo "Please sync the Copilot instructions summary before pushing."
exit 1
fiFAQ: Does Workspace Read CLAUDE.md? (No — Here’s Why)
Does GitHub Copilot Workspace read CLAUDE.md?
No. Copilot Workspace has no knowledge of CLAUDE.md. That file is specific to Anthropic’s Claude Code CLI. Copilot Workspace only reads .github/copilot-instructions.md.
Does Copilot Workspace read AGENTS.md?
No. Despite AGENTS.md being supported by multiple AI coding tools (Claude Code, OpenAI Codex CLI, Aider, Continue), GitHub has not added AGENTS.md support to Copilot Workspace. Copilot Workspace predates AGENTS.md’s widespread adoption, and GitHub’s instruction file for Copilot remains .github/copilot-instructions.md.
Can Copilot Chat in VS Code read AGENTS.md?
Not natively. Copilot Chat reads .github/copilot-instructions.md in the workspace. You can manually add AGENTS.md as a context file by dragging it into the Copilot Chat panel, but it won’t load automatically the way .github/copilot-instructions.md does.
Is there an @import directive that lets copilot-instructions.md include AGENTS.md?
No. Neither file format supports an include or import directive. The reference pattern (writing a comment in copilot-instructions.md pointing to AGENTS.md) communicates intent to humans but has no functional effect on Copilot Workspace.
If I put all my rules in AGENTS.md and nothing in copilot-instructions.md, what happens with Copilot Workspace?
Copilot Workspace operates with no custom instructions — it uses only its training data and the task description you provide. You’ll likely get generic code that doesn’t match your project’s conventions, tech stack choices, or testing requirements.
Does GitHub have plans to support AGENTS.md in Copilot Workspace?
GitHub has not announced native AGENTS.md support for Copilot Workspace as of July 2026. GitHub’s trajectory has been toward their own instruction formats (copilot-instructions.md, GitHub Copilot Extensions) rather than adopting the cross-vendor AGENTS.md standard. Teams working with both tools should maintain both files.
Which file should I treat as the source of truth?
It depends on your team’s primary tool. If most developers use Copilot Workspace as their main AI driver, treat .github/copilot-instructions.md as authoritative and sync summaries to AGENTS.md. If you’re primarily a Claude Code or Codex CLI shop that added Copilot Workspace later, treat AGENTS.md as authoritative and keep .github/copilot-instructions.md as a maintained summary.
Does Copilot Workspace read .cursorrules?
No. .cursorrules is specific to Cursor. Copilot Workspace ignores it entirely.
Keep Secrets Consistent Across Tools
When running multiple AI tools on the same repo, each tool may need access to API keys, database URLs, or service credentials. 1Password CLI’s op run provides a single secrets source that works across all of them — Claude Code, Codex CLI, Cursor’s terminal, and any CI pipeline Copilot Workspace triggers. One entry in 1Password, referenced from every tool’s environment config, no divergence.