Claude Code & GitHub Copilot | Cross-Compatible Prompt File Structure

As I explore GenAI tools I have found myself switching back and forth between GitHub Copilot and Claude Code. Why? Because GitHub Copilot integrates very well on VS Code, while Claude Code has a lot of hype. One of the challenges is that the places where you put general instructions, skills, etc. are different.

In this post, I am sharing how I am currently structuring my files and folders to be used by both. This post can serve as an update to my previous post which was for GitHub Copilot only.

In recent updates, GitHub Copilot has nicely supported CLAUDE.md and .claude/* for many similar functionalities. This makes it easy to have one common place to place prompts (with a few exceptions… since not everything is cross-compatible yet, like agents/).

This post focuses on cross-compatibility between Claude Code (CLI) and GitHub Copilot in agent mode (IDE and CLI). Some of the file referencing patterns here (like markdown links resolving to file content) may not work in GitHub Copilot’s Ask or Edit modes.

What’s Shared (The Good News)

Here’s what works for both tools today.

CLAUDE.md — Your Main Instructions File

GitHub Copilot now reads CLAUDE.md (or .claude/CLAUDE.md) in addition to its own .github/copilot-instructions.md. If you have both, both get loaded — they coexist.

However, this is a one-way street. Claude Code does not read .github/copilot-instructions.md. So to keep things simple, I just use CLAUDE.md as my single instructions file. Both tools pick it up, and I don’t have to maintain two files.

.claude/skills/ — Reusable Prompt Skills

Both tools support SKILL.md files inside .claude/skills/<name>/. These are reusable prompts you can invoke (like slash commands). The format is the same — a markdown file with YAML frontmatter.

.claude/skills/
  commit/SKILL.md
  review-pr/SKILL.md

Each tool also has its own alternative: GitHub Copilot has .github/prompts/ (prompt files), and Claude Code has .claude/commands/ (legacy format). They all feel similar in practice — a markdown file you invoke as a slash command. To keep it simple, I just use .claude/skills/ since both tools read it.

What’s NOT Cross-Compatible (Yet)

MCP Server Config

Both tools support MCP (Model Context Protocol) servers — same protocol, same servers. But the config differs in both location and format:

	Claude Code	GitHub Copilot (VS Code)
Config file	.mcp.json (project root)	.vscode/mcp.json
Top-level key	"mcpServers"	"servers"

So it’s not just a different file — the JSON schema is different too. Claude Code uses "mcpServers" while VS Code uses "servers". Neither reads the other’s file, and there’s no setting on either side to change the config location.

The actual server definitions inside are the same though (command, args, env), so it’s mostly a wrapper difference:

// .mcp.json (Claude Code)
{ "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } } }

// .vscode/mcp.json (GitHub Copilot)
{ "servers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } } }

MCP config comparison — same server definition, different wrapper

You’ll need to maintain both files, but at least the inner content is copy-pasteable.

Agents

Claude Code supports custom agent definitions in .claude/agents/<name>.md. GitHub Copilot has its own agent concept in .github/agents/. The two aren’t interchangeable — Claude Code doesn’t read .github/agents/ and vice versa. Agent teams (multi-agent workflows) are Claude Code only.

Path-Specific Rules / Instruction Files

Both tools support scoping instructions to specific file paths, but they use different formats and locations:

• Claude Code uses .claude/rules/*.md with paths: in the frontmatter
• GitHub Copilot uses .github/instructions/*.instructions.md with applyTo: in the frontmatter

Same concept, different implementation. Neither reads the other’s format.

Keep the full language-specific content in .github/instructions/ and make .claude/rules/ thin wrappers that point to them (e.g., “Follow the Python best practices in .github/instructions/py.instructions.md”). Why? Because .github/instructions/ is also used by VS Code’s non-agent features (code completions, Ask mode, Edit mode) — those features don’t read .claude/rules/. By keeping .github/instructions/ as the source of truth for language rules, you get coverage across all VS Code modes, and Claude Code picks them up via the thin wrapper.

Auto Memory

Claude Code automatically remembers corrections and preferences across sessions in ~/.claude/projects/<project>/memory/. GitHub Copilot has no equivalent — you’d need to put everything in your instructions file.

Hooks & Settings

Both tools have hook systems, but the event types and config formats differ. Claude Code hooks go in settings.json; GitHub Copilot hooks go in .github/hooks/. Settings files are also separate — .claude/settings.json vs VS Code settings. Just maintain them independently.

Sharing Prompt Snippets

In my previous post, I used a custom .github/prompt-snippets/ folder containing shared prompt text (coding standards, commit message style, etc.) that multiple instruction files could reference.

With both tools in play, I’ve moved this to .claude/prompt-snippets/ instead. Since both tools read the same CLAUDE.md, I use both reference syntaxes in one file — Claude Code picks up the @import, GitHub Copilot picks up the markdown link:

# CLAUDE.md

## Coding Standards
@.claude/prompt-snippets/coding-standards.md
[Coding Standards](./.claude/prompt-snippets/coding-standards.md)

## Commit Message Style
@.claude/prompt-snippets/commit-message.md
[Commit Message Guidelines](./.claude/prompt-snippets/commit-message.md)

Using dual reference syntax in CLAUDE.md for both tools

It looks a bit redundant, but each tool resolves the format it understands and ignores the other. One file, both tools get the snippet content.

@import only works in CLAUDE.md files. Claude Code agents, rules, and skills don’t support @import or auto-resolve markdown links to external files. GitHub Copilot in agent mode does resolve markdown links in its instruction files, so this is a Claude Code-specific gap.

The Workaround: Prompt-Level File References

For agents and rules (which aren’t cross-compatible anyway), you can avoid duplicating the full instruction body by simply telling the agent to read a shared snippet:

# .claude/agents/reviewer.md
---
name: reviewer
model: sonnet
tools: ["Read", "Edit", "Grep", "Glob"]
---
You are a code reviewer.
Follow the review guidelines in .claude/prompt-snippets/review-standards.md

Claude Code agent — thin wrapper pointing to shared snippet

# .github/agents/reviewer.md
---
name: reviewer
---
You are a code reviewer.
Follow the review guidelines in .claude/prompt-snippets/review-standards.md

GitHub Copilot agent — same idea, different frontmatter

This works because both Claude Code and GitHub Copilot agents have file read capabilities — they’ll follow the instruction and read the file. It’s a prompt-level instruction, not a file resolution feature, so it’s tool-agnostic.

For rules/instructions, the approach is slightly different. Keep the full content in .github/instructions/ (since VS Code non-agent features like completions, Ask, and Edit also use these), and make .claude/rules/ a thin wrapper:

# .github/instructions/frontend.instructions.md (source of truth — full content here)
---
applyTo: ["src/**/*.tsx", "src/**/*.css"]
---
# Frontend Standards
- Use functional components with hooks
- Use CSS modules or Tailwind
- All interactive elements must be keyboard-navigable
...

.github/instructions/ as the source of truth for language-specific rules

# .claude/rules/frontend.md (thin wrapper → points to .github/instructions/)
---
paths: ["src/**/*.tsx", "src/**/*.css"]
---
Follow the frontend coding standards in .github/instructions/frontend.instructions.md

.claude/rules/ as a thin wrapper pointing to .github/instructions/

Why this way around? Because .github/instructions/ is used by all VS Code Copilot modes — not just agent mode, but also code completions, Ask, and Edit. Claude Code is CLI-only, so .claude/rules/ only matters for Claude Code. By keeping the full content in .github/instructions/, you get the broadest coverage.

The tradeoff: Claude Code’s rule is a soft contract — the LLM reads the referenced file at runtime, unlike @import which loads at launch. In practice though, “follow the instructions in this file” is a very reliable instruction.

My Current Folder Structure

Here’s how I structure a typical repo to work with both:

my-project/
├── CLAUDE.md                       # Main instructions (both read this)
├── .mcp.json                       # MCP config (Claude Code)
├── .vscode/
│   └── mcp.json                    # MCP config (GitHub Copilot in VS Code)
├── .claude/
│   ├── settings.json               # Claude Code settings
│   ├── settings.local.json         # Local overrides (gitignored)
│   ├── prompt-snippets/            # Shared prompt text (the single source of truth)
│   │   ├── coding-standards.md
│   │   ├── commit-message.md
│   │   ├── review-standards.md
│   │   └── frontend-standards.md
│   ├── skills/                     # Shared skills (both read this)
│   │   └── commit/SKILL.md
│   ├── agents/                     # Claude Code agents (thin wrappers)
│   │   └── reviewer.md
│   └── rules/                      # Claude Code rules (thin wrappers → .github/instructions/)
│       └── frontend.md
├── .github/
│   ├── agents/                     # GitHub Copilot agents (thin wrappers)
│   │   └── reviewer.md
│   └── instructions/               # Language-specific rules (source of truth — also used by VS Code non-agent features)
│       └── frontend.instructions.md

Cross-compatible folder structure for Claude Code and GitHub Copilot

The key idea: CLAUDE.md, .claude/skills/, and .claude/prompt-snippets/ are your shared layer. Language-specific rules live in .github/instructions/ as the source of truth (since VS Code non-agent features also use them), and .claude/rules/ are thin wrappers that point there. Agents are thin wrappers with tool-specific frontmatter, pointing to shared snippets.

Quick Comparison Table

Feature	Shared?	Claude Code	GitHub Copilot
Main instructions	Yes	CLAUDE.md	.github/copilot-instructions.md or CLAUDE.md or AGENTS.md
Skills	Yes	.claude/skills/	.claude/skills/ or .github/skills/
Slash commands (alt)	No	.claude/commands/ (legacy)	.github/prompts/
Prompt snippets	Yes*	@import in CLAUDE.md	Markdown links
MCP servers	No	.mcp.json	.vscode/mcp.json
Agents	No	.claude/agents/	.github/agents/
Path-specific rules	No	.claude/rules/	.github/instructions/
Auto memory	No	~/.claude/projects/	Not supported
Hooks	No	settings.json	.github/hooks.json
Settings	No	.claude/settings.json	VS Code settings

*Prompt snippets are shared files, but each tool uses a different syntax to reference them.

Sample Repository

I’ve reworked my github-copilot-prompts repo to follow the patterns described in this post. You can use it as a reference for how to structure your own cross-compatible setup.

Closing Thoughts

The cross-compatibility story is getting better fast. The biggest win is that GitHub Copilot now reads CLAUDE.md and .claude/skills/ — so you can keep most of your prompt engineering in one place without maintaining parallel files.

My advice: start with CLAUDE.md as your single source of truth. Put shared prompt text in .claude/prompt-snippets/. Use .claude/skills/ for reusable commands. Add tool-specific config only where you need to. And keep an eye on updates — this space is moving quickly.