Harness-level selection and use of tools, agents, skills, prompts, and…

Research Question

When should teams choose tools, agent definition files, skills, prompts, instruction files, and AGENTS.md, and what verifiable best practices align with how major harnesses actually select and apply each artifact?

Findings

(Populated from section 6 Synthesis above.)

Executive Summary

• (GitHub Docs: Copilot CLI feature comparison Claude Code features overview, Codex customization] Teams should use instruction files for durable project policy, prompt artifacts for manually launched one-off tasks, skills for reusable on-demand workflows, agent definition files for specialist workers, and tools or Model Context Protocol (MCP) only for capabilities.
• (AGENTS.md specification Anthropic Docs: Claude Code memory, GitHub custom instructions support matrix] AGENTS.md is the strongest portable repository-level core across the surveyed harnesses, but Claude Code still needs a CLAUDE.md entrypoint or import shim for first-class always-on behavior.
• (Visual Studio Code Docs: agent skills Claude Code skills, OpenCode skills, Codex skills] SKILL.md is the clearest cross-harness answer for reusable multi-step procedures because the major ecosystems all document low-cost discovery plus on-demand full loading.
• (GitHub Docs: Custom instructions support matrix Anthropic Docs: Claude Code memory, OpenCode rules, Codex AGENTS.md guide] The safest adoption pattern is layered and minimal: keep always-on files short and factual, move procedures into skills, use prompt files or commands only for human-triggered task launchers, and add custom agents or subagents only when isolation, tool restriction, or model specialization is worth the extra complexity.

Key Findings

1. (GitHub Docs: Copilot CLI feature comparison Claude Code features overview, Codex customization] High confidence: The decisive selection rule is artifact function rather than filename, because the surveyed harnesses consistently separate abilities, durable policy, reusable workflows, and specialist worker definitions into different layers.
2. (AGENTS.md specification GitHub custom instructions support matrix, OpenCode rules, Codex AGENTS.md guide, Anthropic Docs: Claude Code memory] High confidence: AGENTS.md is the most portable repository-level instruction artifact across the surveyed harnesses, but Claude Code still requires a CLAUDE.md wrapper or import pattern for full always-on compatibility.
3. (GitHub Docs: Custom instructions support matrix VS Code custom instructions, GitHub Docs: Copilot CLI custom instructions, GitHub Docs: Create Copilot Spaces] High confidence: GitHub Copilot documents repository instructions, path-specific instructions, prompt files, skills, custom agents, and Copilot Spaces across its public surfaces, so teams still need to choose by surface because GitHub.com cloud agent, VS Code, CLI, and Spaces each load different files and apply different precedence rules.
4. (GitHub Docs: About organizing and sharing context with Copilot Spaces GitHub Docs: Create Copilot Spaces] Medium confidence: Copilot Spaces should be selected for shared retrieval context and curated question answering, while repository instruction files should still hold coding policy for cloud-agent or integrated development workflows.
5. (Anthropic Docs: Claude Code memory Claude Code skills, Claude Code subagents] Medium confidence: A practical Claude Code operating model is CLAUDE.md for always-on facts, skills for reusable procedures or reference bundles, and subagents for isolated specialist work, so long procedural guidance should not remain in CLAUDE.md.
6. (OpenCode Docs: rules OpenCode commands, OpenCode skills, OpenCode agents, OpenCode tools] High confidence: OpenCode documents separate native artifacts for rules, commands, skills, agents, and tools, which makes it a useful public example of the layered selection framework this item recommends.
7. (OpenAI Docs: Codex customization Codex AGENTS.md guide, Codex skills, Codex subagents] Medium confidence: Codex documents a disciplined order of adoption, AGENTS.md first, then skills, then external connectivity through MCP, then subagents only when explicit parallel specialist work is justified.
8. (AGENTS.md specification Anthropic Docs: Claude Code memory, GitHub custom instructions support matrix, VS Code agent skills, Codex AGENTS.md guide] High confidence: The strongest cross-harness best practice is a short portable core in AGENTS.md, plus harness-native compatibility shims only where required, rather than trying to overload prompts, commands, or agent files with permanent repository policy.

Assumptions

• (GitHub Docs: Create Copilot Spaces GitHub custom instructions support matrix] Assumption: Copilot Spaces should be treated as separate from repository instruction inheritance until GitHub documents otherwise. Justification: The current official docs explain Space instructions and attached sources, but do not document automatic loading of repository instruction files into Space chat behavior.

Analysis

• (Visual Studio Code Docs: custom instructions Anthropic Docs: Claude Code memory, Codex AGENTS.md guide] I weighted always-on file behavior most heavily when vendors documented startup loading explicitly, because that is the part of the system teams rely on for baseline policy and because those statements were primary-source, not community extrapolation.
• (Visual Studio Code Docs: agent skills Claude Code skills, OpenCode skills, Codex skills] I treated the convergence on SKILL.md as stronger evidence than any single vendor’s workflow marketing, because four independent ecosystems describe the same authoring unit and the same progressive-disclosure loading model.
• (Anthropic Docs: Claude Code memory GitHub custom instructions support matrix, OpenCode rules, Codex AGENTS.md guide] I resolved the portability tension by privileging documented discovery rules over convenience, which is why the recommendation is a portable AGENTS.md core plus shims instead of pretending that every harness discovers the same path natively.
• (GitHub Docs: Customize the Copilot coding agent development environment Codex MCP, OpenCode tools] I kept runtime setup and external connectivity outside the prompt-selection framework because the official docs consistently place those concerns in setup workflows, configuration, permissions, or MCP, not in instruction bodies.

Risks, Gaps, and Uncertainties

• (GitHub Docs: About organizing and sharing context with Copilot Spaces GitHub Docs: Create Copilot Spaces] Current Copilot Spaces docs describe Space instructions and source retrieval but do not explicitly say "repository instruction files are ignored," so the negative conclusion is based on documented model shape rather than on a direct denial statement.
• (docs.anthropic.com Claude Code’s CLAUDE.md requirement is explicit today, but Anthropic could still add native AGENTS.md loading later without invalidating the broader layered-selection model.
• (developers.openai.com The consulted Codex subagent evidence is strongest on workflow concepts and weaker on repository file-path mechanics for agent definitions, because the retrieved primary pages focused more on concepts than on local file layout for subagent profiles.
• (GitHub Docs: Copilot CLI feature comparison Claude Code features overview, OpenCode rules, Codex customization] None of these uncertainties undermines the core conclusion that teams should separate durable policy, reusable workflows, manual task launchers, and specialist worker definitions rather than collapsing them into a single Markdown artifact.

Open Questions

• (GitHub Docs: About organizing and sharing context with Copilot Spaces GitHub Docs: Create Copilot Spaces] Will GitHub add automatic repository instruction inheritance to Copilot Spaces, or will Spaces remain intentionally separate from repository-level coding policy?
• (Anthropic Docs: Claude Code memory AGENTS.md specification] Will Claude Code eventually read AGENTS.md natively, or will CLAUDE.md remain the required compatibility entrypoint even as the open standard spreads?
• (OpenAI Docs: Codex skills OpenCode skills, VS Code agent skills] Will the current convergence on Agent Skills produce stronger cross-tool packaging interoperability, or will plugins and dependency metadata keep skills only partially portable across harnesses?

sources

Starting points, papers, articles, videos, repos, docs.

• [x] GitHub Docs: Configure custom instructions for GitHub Copilot — - baseline instruction-file behavior in GitHub Copilot
• [x] GitHub Docs: About organizing and sharing context with Copilot Spaces — - product-level context model and reusable instruction spaces
• [x] GitHub Docs: Create Copilot Spaces — - Space instructions and source attachment behavior
• [x] GitHub Docs: Customize the Copilot coding agent development environment — - agent-oriented repository controls and workflow integration
• [x] GitHub Docs: Copilot CLI feature comparison — - artifact boundary definitions for tools, skills, hooks, subagents, and custom agents
• [x] GitHub Docs: Copilot CLI custom instructions — - repository, path, and AGENTS.md loading in Command Line Interface (CLI)
• [x] GitHub Docs: Create custom agents for Copilot CLI — - .agent.md agent definition behavior
• [x] GitHub Docs: Custom instructions support matrix — - surface-by-surface support matrix
• [x] Visual Studio Code Docs: GitHub Copilot customization overview — - Visual Studio Code (VS Code) customization map
• [x] Visual Studio Code Docs: custom instructions — - always-on and file-based instructions
• [x] Visual Studio Code Docs: prompt files — - manually invoked prompt artifacts
• [x] Visual Studio Code Docs: agent skills — - open-standard SKILL.md behavior in Copilot
• [x] Visual Studio Code Docs: custom agents — - .agent.md personas, tools, and handoffs
• [x] Anthropic Docs: Claude Code overview — - Claude Code artifact model and execution context
• [x] Anthropic Docs: Claude Code memory — - repository and user instruction persistence behavior
• [x] Claude Code Docs: features overview — - layering of instruction files, skills, subagents, hooks, and Model Context Protocol (MCP)
• [x] Claude Code Docs: skills — - SKILL.md behavior and invocation control
• [x] Claude Code Docs: subagents — - .claude/agents/ subagent definitions and preload behavior
• [x] Claude Code Docs: commands — - bundled skills versus fixed slash commands
• [x] OpenCode Docs — - top-level OpenCode model
• [x] OpenCode Docs: rules — - AGENTS.md, CLAUDE.md, and custom instruction precedence
• [x] OpenCode Docs: skills — - native SKILL.md discovery and permissions
• [x] OpenCode Docs: agents — - primary agents, subagents, and Markdown agent files
• [x] OpenCode Docs: commands — - command files as prompt templates
• [x] OpenCode Docs: tools — - tool and permission model
• [x] OpenAI Docs: Codex overview — - Codex harness concepts and task execution model
• [x] OpenAI Docs: Codex customization — - artifact stack for AGENTS.md, skills, subagents, and MCP
• [x] OpenAI Docs: Codex custom instructions with AGENTS.md — - AGENTS.md discovery and precedence
• [x] OpenAI Docs: Codex skills — - .agents/skills and progressive disclosure
• [x] OpenAI Docs: Codex subagents — - explicit parallel subagent workflows
• [x] OpenAI Docs: Codex MCP — - external tool configuration
• [x] AGENTS.md specification — - cross-tool convention for repository-level agent instructions