Skills and Instruction Files: What to Put in CLAUDE.md and AGENTS.md, and How to Manage Shared Rules
What you’ll learn
- How Skills and startup instruction files differ in role and loading time
- How to decide what belongs in CLAUDE.md or AGENTS.md
- Which operations Markdown instructions alone cannot prevent, and how to manage shared rules across several AI tools
The roles of Skills and startup instruction files
When assigning work to an AI, putting assumptions needed for every task and procedures needed only for specific tasks into the same file makes the instructions longer and harder to update.
The distinction is when the information is needed and which tasks need it. Project-wide policies and precautions belong in startup instruction files read when work begins. Procedures for specific tasks, such as writing a blog post or investigating a failure, belong in Skills. A Skill is a collection of instructions and supporting material that the AI loads as needed.
On this site, instructions for Claude Code and Codex are managed according to when they are loaded and which tasks they apply to.
Neither kind of document guarantees that operations are restricted. When access to secrets or execution of dangerous commands must be prevented, use permissions and automated checks alongside written instructions.
This article first explains which files each product reads, then covers where to place instructions, how to restrict operations, and how to manage shared rules across several AI tools.
Differences in loading time
Skills and startup instruction files generally serve these roles.
| Type | Role | Example files |
|---|---|---|
| Startup instruction files | Provide project assumptions, policies, precautions, and validation commands from the start of a task | CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md |
| Skills | Provide procedures, specialist workflows, reference material, and scripts for specific tasks when needed | SKILL.md |
Short rules needed for every task belong in startup instruction files; detailed procedures needed only for particular tasks belong in Skills. The files actually read and their scope vary by product, as explained below.
Skills: procedures and resources loaded when needed
Skills in Claude Code, Codex, GitHub Copilot, and Antigravity all provide task procedures to the AI when needed.
Claude Code’s official documentation describes a Skill as instructions written in SKILL.md that Claude uses when relevant to the task or when a user invokes it with /skill-name.[1]
In Codex, Skills add capabilities for specific tasks. Codex initially sees each Skill’s name, description, and path, then reads the full SKILL.md when needed. This is called progressive disclosure: loading information in stages as it becomes necessary.[2]
GitHub Copilot treats Agent Skills as folders containing instructions, scripts, and resources. Its official documentation describes support in Copilot cloud agent, Copilot code review, GitHub Copilot CLI, GitHub Copilot app, and agent mode in VS Code and JetBrains IDEs. Agent mode lets the AI perform multiple operations while working through a task.[3]
Google introduced Antigravity as an “agentic development platform,” a platform for AI agents to carry out development work.[7] Its official site explains that Antigravity 2.0 customization supports global Skills and workspace-specific Skills. A workspace is the project area used for work. It also supports MCP, which connects AI to external tools and data, and JSON Hooks, which run automated processes at specified points, such as before or after a command executes.[8]
All four share the idea of loading Skill instructions when the relevant task needs them, rather than passing every instruction to the AI each time.
Startup instruction files: assumptions provided at the start
Startup instruction files are prepared for the AI to read when work begins. They contain project background and ongoing policies rather than individual procedures like those in Skills.
Claude Code describes CLAUDE.md as the place for persistent project, user, and organization instructions. According to its official documentation, Claude reads this Markdown file at the start of a session. It is suitable for build commands, coding standards, and project structure. A build turns source code into artifacts that can be run or published.[4]
For Codex, AGENTS.md is the entry point for custom instructions. Codex reads AGENTS.md and AGENTS.override.md from the global Codex home, the user-wide configuration area, and along the directory hierarchy from the project root to the current working directory. Instructions in lower directories are appended after those from higher directories.[5]
GitHub Copilot supports .github/copilot-instructions.md for repository-wide instructions. A repository is a place where a project’s files are managed together. It also supports .github/instructions/NAME.instructions.md for path-specific instructions and AGENTS.md inside the repository for AI agent instructions. GitHub Docs explains that the AGENTS.md closest to the target file takes precedence.[6]
Antigravity’s official changelog records added support for reading rules from AGENTS.md in addition to GEMINI.md.[9] When organizing Antigravity instruction files, it is therefore safest to treat both as relevant to rule loading.
Each file’s target and suitable content
Checking which tool reads a file and where its instructions apply makes it easier to choose a location than judging by the filename alone.
| File | Main target | Suitable content |
|---|---|---|
| CLAUDE.md | Claude Code | Ongoing project policies, work constraints, and commands |
| AGENTS.md | Codex, GitHub Copilot agent features, and similar tools | Repository policies, validation procedures, and directory-specific rules |
| GEMINI.md | Antigravity | Project rules for Antigravity/Gemini-oriented tools |
| .github/copilot-instructions.md | GitHub Copilot | Repository-wide background and build and test methods |
| .github/instructions/*.instructions.md | GitHub Copilot | Instructions for specific paths or file types |
| SKILL.md / Skills | Claude Code, Codex, GitHub Copilot, Antigravity, and other tools | Procedures, checklists, reference material, and scripts for specific tasks |
The filename matters too. The name commonly used in official documentation is the plural AGENTS.md, rather than AGENT.md. When adding instruction files to a repository, check the exact name recognized by the tool you use.
Criteria for choosing where instructions belong
Loading time and scope provide the following basis for separating project-wide assumptions from task-specific procedures.
| Content | Location |
|---|---|
| The repository policy for handling npm run build | Startup instruction file |
| The policy of writing Japanese first and creating an English version with the same structure | Startup instruction file; shared rules if needed |
| Specific procedures for investigating GitHub Actions failures | Skill |
| Procedures for checking blog structure, citations, and voice | Skill |
| A different validation command used only in a specific folder | Nested AGENTS.md or path-specific instructions |
| Adding reusable capabilities that include external services or MCP | A Plugin, an extension package, or an agent extension |
The central question is whether the information is needed for every task or only for a specific task. The former belongs in startup instruction files; the latter belongs in Skills. When conditions differ by folder, use directory-specific or path-specific instructions.
Markdown instructions and operation restrictions
CLAUDE.md, AGENTS.md, and SKILL.md are information an AI agent consults when making decisions: its context. Writing “do not execute this” does not by itself guarantee that dangerous commands cannot run or that secrets cannot be accessed.
When operations must be restricted or results checked, use execution mechanisms alongside written instructions.
| Mechanism | Role |
|---|---|
| hooks | Run automated processes before or after events such as command execution to check or block specific operations |
| sandbox | Run processes in an environment with restricted permissions or execution scope |
| approval policy | Define when a person must approve an operation before it proceeds |
| CI | Run tests and validation automatically through tools such as GitHub Actions |
| Validation scripts | Check files or artifacts against specified conditions |
Claude Code’s official documentation likewise explains that CLAUDE.md provides context rather than configuration that enforces restrictions. Blocking specific operations requires execution mechanisms such as settings or hooks.[4]
Codex’s AGENTS.md also provides custom instructions read before work begins. Actual restrictions on operations are handled through approval rules, sandboxing, and permissions.[5]
Team rules are therefore clearer when they distinguish what documents instruct, what settings restrict, and what automated checks verify. Simply saying “this file prohibits the operation” does not explain the difference between an instruction and a mechanism that prevents the operation.
Managing shared rules across several AI tools
When Claude Code, Codex, and GitHub Copilot work in the same repository, copying the same lengthy rules into each instruction file makes it easy for their contents to diverge when only some copies are updated.
On this site, shared rules live under shared/, while AGENTS.md and the Claude-facing startup instruction files retain the short instructions needed when work begins. These short startup instructions are called a bootstrap contract: they define what to read first and which rules to apply.
For example, citation rules, build policies, and rules for handling folders safely live under shared/rules/, which each agent is expected to read.
| Content or target | Location |
|---|---|
| Shared rules | shared/rules/ |
| Codex startup instructions | AGENTS.md |
| Claude Code startup instructions | CLAUDE.md |
| Copilot startup instructions | .github/copilot-instructions.md or AGENTS.md |
| Antigravity startup instructions | GEMINI.md or AGENTS.md |
| Task-specific procedures | Skills that each tool can read |
Choosing one canonical location for shared rules reduces the burden of manually updating the same content in several places. Each tool’s startup instruction file serves as an entry point to those rules, while detailed task procedures belong in Skills.
Before choosing file locations, however, check the official specifications for the files each product currently reads, their scope, and their precedence.
Summary: separate project-wide assumptions from task-specific procedures
Startup instruction files contain short assumptions and policies needed for every task. Skills contain procedures and resources needed for specific tasks. Hooks, sandboxing, approval rules, CI, and validation scripts restrict operations or check results.
When using several AI tools, choosing a shared location for common rules and directing each tool there from its startup instructions makes updates easier to manage. Sorting existing instructions into “assumptions for every task,” “procedures for specific tasks,” and “conditions enforced by settings or automated checks” also makes their appropriate locations clearer.
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.