Agent instruction loading and skills access

Research Question

Given the current repo setup -- instructions in .github/copilot-instructions.md, skills submodule at .github/skills/, no AGENTS.md at root, no CLAUDE.md at root -- what does each agent actually load at the point it starts work, and does it have access to the skills?

Q1 -- GitHub Copilot coding agent (GitHub issue → assign to Copilot → draft pull request (PR))

• When a GitHub issue is assigned to Copilot via the GitHub Issues User Interface (UI), which files does it read before starting planning? Does it read .github/copilot-instructions.md automatically? Does it read .github/skills/? Does it look for AGENTS.md at the repo root?
• What is the confirmed loading order: does .github/copilot-instructions.md take priority over a root AGENTS.md if both exist?
• Does the Copilot coding agent materialise the skills submodule (run git submodule update) before reading .github/skills/, or does it see an empty directory?

Q2 -- Claude iOS app (code section / feature)

• When the Research repo is opened in Claude's iOS code feature, which files does Claude load into context? Does it look for CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md? Does it read any of them automatically?
• Can Claude iOS access .github/skills/? What path does it scan for instructions?
• Does the code feature on iOS behave identically to Claude Code Command Line Interface (CLI) in terms of file-loading behaviour, or is it a different surface with different rules?

Q3 -- The role of AGENTS.md for both agents

• AGENTS.md is the emerging cross-tool convergence format (supported by Copilot, Claude Code, Cursor, Aider, Codex, Gemini CLI). Architecture Decision Record (ADR)-0006 deleted it from this repo in favour of .github/copilot-instructions.md. Does the Copilot coding agent read AGENTS.md at the repo root when assigned a GitHub issue? Does Claude iOS?
• If both agents read AGENTS.md, is the right answer to restore it as a thin pointer to .github/copilot-instructions.md, or to move content back to AGENTS.md and have copilot-instructions.md point to it?
• Does restoring AGENTS.md break ADR-0006 or supersede it?

Findings

Executive Summary

The GitHub Copilot coding agent reads .github/copilot-instructions.md automatically when assigned a GitHub issue, and since August 2025 also reads AGENTS.md, CLAUDE.md, and GEMINI.md when present. Claude Code on the web (the Claude iOS app's code feature) reads CLAUDE.md automatically and is inferred to read AGENTS.md based on cross-tool documentation patterns, but does NOT read .github/copilot-instructions.md -- this path is Copilot-specific. The current repo has neither CLAUDE.md nor AGENTS.md at root, meaning every Claude Code session starts without project instructions, context, or research workflow guidance. The fix is to create AGENTS.md at the repo root pointing to or containing the instructions; this single change closes the Claude Code instruction gap without disrupting the Copilot coding agent setup. ADR-0006's stated assumption that .github/copilot-instructions.md was "sufficient for all agents" was incorrect and must be amended.

Key Findings

1. The GitHub Copilot coding agent, when triggered by a GitHub issue assignment, reads .github/copilot-instructions.md automatically before starting work, as confirmed by GitHub's official documentation and the August 2025 coding agent changelog. (high confidence)

2. The Copilot coding agent has supported AGENTS.md at the repo root since August 2025, and when both AGENTS.md and .github/copilot-instructions.md exist, both files are loaded and provided to the agent as context -- the dual-loading behaviour is documented for the Copilot CLI and inferred to apply to the coding agent. (medium confidence -- coding-agent-specific dual-loading confirmation not in primary source)

3. The Copilot coding agent does not initialise git submodules by default, meaning the .github/skills/ submodule directory appears as an empty folder during all agent sessions unless a copilot-setup-steps.yml workflow is configured with submodules: recursive and a token with access to the submodule repository. (high confidence)

4. The Claude iOS app's code feature is Claude Code on the web: Anthropic's remote code execution environment where the user selects a GitHub repository and Claude works on tasks in a sandboxed cloud environment, creating a pull request (PR) when complete. (high confidence)

5. Claude Code on the web follows the same instruction file loading behaviour as Claude Code CLI: it reads CLAUDE.md and AGENTS.md at the repository root automatically, and does not read .github/copilot-instructions.md because that path is Copilot-specific and is not part of Claude Code's file discovery logic. (medium confidence -- AGENTS.md reading is inferred from VS Code docs and cross-tool patterns, not from a primary Anthropic statement)

6. The current repo has no CLAUDE.md and no AGENTS.md at the root, which means Claude Code (in all surfaces including iOS) starts every session without any of the project's non-negotiable constraints, research workflow rules, coding standards, or session log requirements. (high confidence)

7. ADR-0006 (2026-03-07) removed AGENTS.md based on the incorrect assumption that .github/copilot-instructions.md was sufficient for all agents, leaving Claude Code without an instruction entry point; this is a documented gap in the ADR's reasoning that warrants an amendment. (high confidence)

8. Restoring AGENTS.md at the repo root resolves the Claude Code instruction gap without disrupting the Copilot coding agent setup, because the Copilot CLI documentation confirms both files are loaded when present and this behaviour is inferred to extend to the coding agent. (medium confidence -- follows from the same dual-loading inference as KF2)

9. The practitioner-recommended approach for multi-agent instruction sharing is to keep .github/copilot-instructions.md as the Copilot-specific file and to place AGENTS.md (or symlink it) at the repo root as the cross-agent entry point read by Claude Code, Cursor, Aider, Codex, Gemini CLI, and others. (medium confidence -- well-supported by practitioner evidence but not explicitly stated in any single official source)

10. Enabling submodule access for the Copilot coding agent requires creating .github/workflows/copilot-setup-steps.yml with an actions/checkout@v4 step using submodules: recursive and a PAT stored as a secret in the copilot GitHub Actions environment with read access to davidamitchell/Skills. (high confidence)

Assumptions

• Assumption 1: The Claude iOS code feature follows the same instruction loading behaviour as Claude Code CLI. Justification: Both are Claude Code product variants. Anthropic's "Claude Code on the web" help article confirms the remote execution architecture is the same product accessed via browser or iOS app. No Anthropic documentation contradicts this. Gap: Anthropic has not published iOS-specific instruction loading documentation -- this remains an inference from the product architecture.
• Assumption 2: ADR-0006's assumption that .github/copilot-instructions.md is sufficient for all agents was incorrect. Justification: Confirmed by evidence that Claude Code reads CLAUDE.md/AGENTS.md, not .github/copilot-instructions.md. The ADR was written in March 2026 before this verification was done.
• Assumption 3: Restoring AGENTS.md at root will be read by Claude Code on the web (iOS). Justification: Claude Code on the web accesses the repository via GitHub; root files are accessible. No evidence of exclusions for cloud execution. Inference from Claude Code CLI behaviour which is confirmed to read root AGENTS.md.

Analysis

How evidence was weighed: Primary sources (GitHub official documentation, Anthropic official documentation) provided the foundational facts. Community discussion threads provided confirmation for the submodule gap -- an area where official documentation is silent. Practitioner articles (symlink patterns) confirmed the Claude Code file-loading behaviour by demonstrating the workaround that would be unnecessary if Claude Code read .github/copilot-instructions.md natively.

Trade-offs:

• Option A (add AGENTS.md at root with full content): Simple for Claude Code users, but creates a second place to maintain instructions alongside .github/copilot-instructions.md. Risk: content drift.
• Option B (add AGENTS.md as thin pointer): Reduces maintenance burden. AGENTS.md says "See .github/copilot-instructions.md for full instructions." Claude Code loads the pointer but must then discover the full file separately. This may not work if Claude Code does not follow the pointer automatically -- it depends on whether Claude Code follows file references in AGENTS.md. Not confirmed.
• Option C (symlink AGENTS.md -> .github/copilot-instructions.md): Works perfectly in any git-cloned environment. In GitHub's cloud execution environments (both Copilot and Claude Code on the web), symlinks are likely followed correctly because the environments use standard Linux git checkouts, but this is an inference.
• Option D (add CLAUDE.md instead): Equivalent to Option A but Anthropic-specific. Provides no benefit over AGENTS.md for cross-tool coverage.

Recommended resolution: Option A (restore AGENTS.md with full instructions content, or content that references and supplements copilot-instructions.md). [Opinion] This is the most direct solution with the best-confirmed loading behaviour across both agents.

ADR-0006 assessment: [Opinion] The decision's intent (a single unified instruction source) was sound. The execution was incomplete: the assumption that .github/copilot-instructions.md covers all agents was not verified at the time. The right outcome is not to reverse ADR-0006 but to amend it: .github/copilot-instructions.md is the canonical content file; AGENTS.md is the cross-agent entry point that makes the content accessible to non-Copilot tools.

Risks, Gaps, and Uncertainties

• Claude Code on the web submodule access: Whether Claude Code on the web initialises git submodules is not documented by Anthropic. If it does not, .github/skills/ will be empty for Claude Code sessions too. Research needed: check whether Claude Code on the web's GitHub checkout includes submodule initialisation.
• iOS-specific loading confirmation: Anthropic has not published iOS-specific instruction loading documentation. The finding that iOS behaves identically to Claude Code on the web is an inference from product architecture, not a confirmed primary source.
• Pointer behaviour in AGENTS.md: Whether Claude Code automatically follows a file reference pointer in AGENTS.md (Option B above) is unconfirmed. The safest option is to include the full content rather than a pointer.
• Copilot plan tier differences: GitHub documentation does not explicitly confirm whether the coding agent's instruction loading behaviour differs by plan tier (Pro, Business, Enterprise). The changelog and documentation appear to apply to all tiers but this has not been verified.

Open Questions

1. Does Claude Code on the web initialise git submodules, or does it also see .github/skills/ as an empty directory? If so, skills are inaccessible from both primary entry points. (Proposed backlog item: 2026-03-29-claude-code-web-submodule-access.md)
2. Does creating AGENTS.md as a thin pointer to .github/copilot-instructions.md work, or does Claude Code require the content to be directly in the file it loads?
3. Does the Copilot coding agent's instruction loading behaviour differ between plan tiers (Copilot Pro, Business, Enterprise)?
4. What is the correct ADR amendment format for updating ADR-0006 to reflect the Claude Code gap?

Output

• Type: knowledge
• Description: Confirmed instruction loading for Copilot coding agent (reads .github/copilot-instructions.md and AGENTS.md) and Claude Code on the web / iOS (reads CLAUDE.md and AGENTS.md, not .github/copilot-instructions.md). Confirmed submodule gap for Copilot coding agent. Identified instruction gap for Claude Code due to absent AGENTS.md/CLAUDE.md. Recommended actions: restore AGENTS.md at root; create copilot-setup-steps.yml for submodule access; amend ADR-0006.
• Links:
  • github.blog -- definitive Copilot coding agent instruction loading confirmation
  • www.anthropic.com -- Claude Code CLAUDE.md loading behaviour confirmed
  • docs.github.com -- Copilot coding agent environment setup (basis for submodule fix)

Open Questions

• Does the Copilot coding agent run git submodule update --init before reading .github/skills/?
• Does AGENTS.md take precedence over .github/copilot-instructions.md or vice versa for the Copilot coding agent?
• Does Claude iOS code feature recursively scan parent directories for CLAUDE.md the same way Claude Code CLI does?