---
type: reference
title: Agent Instruction Files and Agent Skills
description: Best practices for AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills SKILL.md standard.
tags:
  - agents-md
  - claude-md
  - system-md
  - agent-skills
  - unverified
timestamp: 2026-08-11
---
verified: 2026-08-28

# Agent Instruction Files and Agent Skills

This page explains the files that control how an AI coding agent works in a project. Use it when you create or review agent behavior configuration.

## AGENTS.md

`AGENTS.md` is the open, cross-tool format for coding-agent instructions. The Agentic AI Foundation (under the Linux Foundation) stewards it. Over 20 coding agents support it, including Cursor, Codex, and Claude Code.

The format is plain Markdown. It has no required fields. Any heading structure works. Agents read the nearest `AGENTS.md` in the directory tree. In a monorepo, the agent uses a nested `AGENTS.md` per package.

Include these sections in an `AGENTS.md`:

* Project overview.
* Setup and build commands.
* Code style guidelines.
* Testing instructions.
* Pull request instructions.
* Security considerations.
* Deployment steps.
* Commit message conventions.

Agents load content progressively. Put a short summary at the top. Put detailed instructions in later sections.

## CLAUDE.md

`CLAUDE.md` is Anthropic's tool-specific instruction file. Claude Code reads `CLAUDE.md` by default, not `AGENTS.md`. Files load in this order:

1. Managed policy (`/etc/claude-code/CLAUDE.md`).
2. User scope (`~/.claude/CLAUDE.md`).
3. Project scope (`./CLAUDE.md`).
4. Local scope (`./CLAUDE.local.md`).

Keep each file under 200 lines. Use the `@path/to/file` syntax to import other files. Use path-scoped rules in `.claude/rules/*.md` with `paths` frontmatter for directory-specific rules.

To make a repository work in both AGENTS.md and CLAUDE.md workflows, create a `CLAUDE.md` that imports `AGENTS.md` with the `@AGENTS.md` syntax, or use a symlink.

## SYSTEM.md

`SYSTEM.md` sets the system-level role and behavior for an agent. It establishes the persona, the prime directive, and the binding rules. In the pi-era setup, `/home/dank/.pi/agent/SYSTEM.md` defined the Comrade Chief Designer persona and the ASD-STE100 voice rules; the live equivalent is `~/.omp/agent/APPEND_SYSTEM.md`.

Use `SYSTEM.md` for stable, cross-project rules. Use `AGENTS.md` for project-specific context. Do not duplicate content between them. Keep the division of labor clear.

## Agent Skills Standard

An agent skill is a directory that contains a `SKILL.md` file. Skills extend an agent's capabilities. The open standard lives at [agentskills.io](https://agentskills.io). Over 50 agents support it.

The `SKILL.md` frontmatter includes these fields:

```yaml
---
name: my-skill
description: What this skill does
license: MIT
compatibility: node>=18
metadata:
  internal: false
---
```

The `name` field is required and must use lowercase alphanumeric plus hyphens. The `description` field is required. Keep the name under 64 characters. Keep the description under 1024 characters.

Skills use progressive disclosure in three stages:

* Discovery: the agent loads only the name and description at startup.
* Activation: the agent reads the full `SKILL.md` when a task matches.
* Execution: the agent follows the instructions and reads resources on demand.

This keeps the context footprint small.

## Distribution

Distribute skills through npm packages with a `pi` manifest, or through the `skills` CLI from Vercel Labs. See the [Skills Documentation](../skills/index.md) pages for details.

## Citations

* [agents.md](https://agents.md/)
* [OpenAI Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) (unverified — returned 403)
* [Claude Code memory documentation](https://code.claude.com/docs/en/memory)
* [Agent Skills standard](https://agentskills.io/)
* [agentskills/agentskills](https://github.com/agentskills/agentskills)
* [vercel-labs/skills](https://github.com/vercel-labs/skills)

## See Also

* [SDLC and Tooling](sdlc.md)
* [Skills Ecosystem](/skills/ecosystem.md)