AI Agent Skills vs Instruction Files: When to Use Each

Jun 25, 2026 Updated Sep 16, 2026

Article cover for “AI Agent Skills vs Instruction Files: When to Use Each” over a pastel ringed planet and orbital lines

What you’ll learn

How loading time and role distinguish Skills from startup instruction files
Criteria for deciding what belongs in CLAUDE.md, AGENTS.md, and related files
How to manage common rules across multiple AI tools while recognizing the limits of Markdown instructions

Use Loading Timing to Separate Skills from Instruction Files

Put assumptions needed for every task in startup instruction files, and keep procedures for a specific task in Skills. Using Claude Code and Codex together on this site showed me that aligning load timing and scope works better than duplicating every instruction. Rules that require enforcement must connect to permissions or deterministic checks instead of relying on either Markdown document alone.

By the end of this article, you will have practical criteria for answering “Which information belongs in startup instructions, and which belongs in an on-demand Skill?” in your own context.

Skills Load When Needed; Startup Instructions Load Before Work Begins

There are two broad categories.

Type	Role	Examples
Startup instruction files	Provide project assumptions, policies, cautions, and validation commands from the start	`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`
Skills	Provide task-specific procedures, specialist workflows, references, and scripts only when needed	`SKILL.md`

In practice, short project-wide rules belong in startup instruction files. Longer procedures that are only relevant to specific tasks belong in Skills.

Skills are task procedures loaded when needed

Claude Code Skills, Codex Skills, GitHub Copilot Skills, and Antigravity Skills are all mechanisms for giving task-specific procedures to an agent when needed. Claude Code documentation describes a Skill as instructions written in SKILL.md that Claude can use when relevant or when invoked with /skill-name.[1]

Codex also uses Skills to add task-specific capabilities. Codex first sees each Skill’s name, description, and path, then reads the full SKILL.md only when it decides to use that Skill, following a progressive disclosure model.[2]

GitHub Copilot treats Agent Skills as folders of instructions, scripts, and resources. GitHub Docs says they work with Copilot cloud agent, Copilot code review, GitHub Copilot CLI, the GitHub Copilot app, and agent mode in VS Code and JetBrains IDEs.[3]

Google describes Antigravity as an agentic development platform. The official Antigravity site describes Antigravity 2.0 customization in terms of global or workspace-specific Skills, MCPs, and JSON Hooks (an automatic action that runs at a defined timing, such as before or after a command).[7][8]

The shared idea is that a Skill is not a large block of instructions loaded into every request. It is a procedure the agent reads when the task calls for it.

Startup instruction files are read before the work begins

Startup instruction files work in the opposite direction. They are meant to be part of the agent’s starting context.

Claude Code uses CLAUDE.md for persistent project, user, or organization instructions. The official documentation describes CLAUDE.md as a Markdown file Claude reads at the start of a session, suitable for build commands, coding standards, and project structure.[4]

Codex uses AGENTS.md as its custom-instruction entry point. Codex reads guidance from the Codex home directory, the project root, and the path down to the current working directory, including files such as AGENTS.md and AGENTS.override.md.[5]

GitHub Copilot supports .github/copilot-instructions.md for repository-wide instructions, .github/instructions/NAME.instructions.md for path-specific instructions, and AGENTS.md for AI agent instructions. GitHub Docs also explains that one or more AGENTS.md files can live inside the repository and that the nearest one takes precedence for agent work.[6]

For Antigravity, the official changelog says support was added for reading rules from AGENTS.md in addition to GEMINI.md.[9] When comparing startup instruction files, it is therefore safer to treat both GEMINI.md and AGENTS.md as relevant rule files for Antigravity.

Instruction Files Target Runtimes; SKILL.md Defines Task Procedures

File	Main target	Best suited for
`CLAUDE.md`	Claude Code	Project policies, work constraints, and commands Claude Code should receive at session start
`AGENTS.md`	Codex and GitHub Copilot agent surfaces	Repository policies, validation steps, and directory-specific rules for AI agents
`GEMINI.md`	Antigravity	Project rules intended for Antigravity/Gemini-oriented workflows
`.github/copilot-instructions.md`	GitHub Copilot	Repository-wide background, build guidance, and test guidance for Copilot
`.github/instructions/*.instructions.md`	GitHub Copilot	Instructions that apply only to specific paths or file types
`SKILL.md` / Skills	Claude Code, Codex, GitHub Copilot, Antigravity, and other compatible agents	Task procedures, checklists, references, and scripts

One naming detail matters: the official file name commonly used here is AGENTS.md, not AGENT.md. When creating the repository entry point, use the plural file name unless a specific tool documents something else.

Put Persistent Assumptions in Instruction Files and Task Procedures in Skills

I find this split practical.

Content	Put it here
The repository policy for how `npm run build` should be handled	Startup instruction file
Write Japanese first, then create the English version with the same structure	Startup instruction file, and shared rules if needed
Step-by-step process for investigating GitHub Actions failures	Skill
Blog drafting procedure, citation rules, and style checks	Skill
A different validation command for one folder	Nested `AGENTS.md` or path-specific instructions
A reusable extension that includes external services or MCP	Plugin or agent extension

In short: project-wide assumptions belong in startup instruction files; task-level procedures belong in Skills.

Markdown instructions are not enforcement boundaries

CLAUDE.md, AGENTS.md, and SKILL.md guide agent behavior by providing context. Writing them does not guarantee by itself that dangerous commands are blocked or that secrets cannot be accessed; enforcement needs execution-layer mechanisms such as hooks, sandboxing, approval policy (a permission rule that asks a human to confirm an action before an AI tool proceeds), CI (the automated test and validation layer, often run through tools such as GitHub Actions), or review scripts.

Claude Code documentation explicitly describes CLAUDE.md content as context rather than enforced configuration. If an action must be blocked, the execution layer needs settings, hooks, or a similar mechanism.[4]

Codex also treats AGENTS.md as custom instructions read before work begins, while execution control belongs to layers such as approvals, sandboxing, and permissions.[5]

So I avoid saying “this Markdown file prevents the action.” A safer design is: the Markdown file gives the instruction, and hooks, sandboxing, CI, or review scripts verify or enforce the rule where enforcement is required.

Design for multiple agents

If Claude Code, Codex, and GitHub Copilot all work in the same repository, copying the same long rule text into every entry file creates drift quickly.

For this site, I keep shared rules under shared/ and keep AGENTS.md and the Claude-facing entry files as thin bootstrap contracts. Citation policy, build behavior, and folder-safety rules live under shared/rules/, and each agent entry point is expected to route back to those shared sources.

That gives this division:

Shared rules: shared/rules/
Codex entry point: AGENTS.md
Claude Code entry point: CLAUDE.md
Copilot entry points: .github/copilot-instructions.md and AGENTS.md
Antigravity entry points: GEMINI.md and AGENTS.md
Task procedures: Skills that the relevant tools can read

Choosing one source of truth is easier to maintain than manually pasting the same policy into several files.

Summary: Separate Skills and Instruction Files by Load Timing and Enforcement

Skills and startup instruction files both provide context to AI, but they are used at different times.

CLAUDE.md, AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are for short assumptions that should be available from the start.
SKILL.md is for specialist procedures that should load only when needed.
Claude Code primarily uses CLAUDE.md, Codex uses AGENTS.md, GitHub Copilot uses .github/copilot-instructions.md and AGENTS.md, and Antigravity uses GEMINI.md and AGENTS.md.
Markdown instructions should be paired with hooks, sandboxing, approvals, CI, or review scripts when a rule needs mechanical verification.

The more AI agents a repository uses, the more instruction files it will have. The issue is not the number of files. The important part is separating startup rules, on-demand Skills, and deterministic validation.

The first action is to sort existing instructions into three columns: needed for every task, needed only for a specific task, and requiring deterministic enforcement. The files and precedence each product supports can change, so verify the current official behavior before choosing their final locations.

References

Anthropic, Extend Claude with skills, Claude Code Docs
OpenAI, Build skills, ChatGPT Learn
GitHub Docs, About agent skills, GitHub Docs
Anthropic, How Claude remembers your project, Claude Code Docs
OpenAI, Custom instructions with AGENTS.md, ChatGPT Learn
GitHub Docs, Adding repository custom instructions for GitHub Copilot, GitHub Docs
Google Developers Blog, Build with Google Antigravity, our new agentic development platform, November 20, 2025
Google Antigravity, Antigravity 2.0, Google
Google Antigravity, Changelog, Google

For the latest releases and updates, check the official website and official documentation.