command-center/omp-docs/engineering/agents-files.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
reference	Agent Instruction Files and Agent Skills	Best practices for AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills SKILL.md standard.	agents-md claude-md system-md agent-skills unverified	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 this setup, /home/dank/.pi/agent/SYSTEM.md defines the Comrade Chief Designer persona and the ASD-STE100 voice rules.

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. Over 50 agents support it.

The SKILL.md frontmatter includes these fields:

---
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 pages for details.

Citations

• agents.md
• OpenAI Agentic AI Foundation (unverified — returned 403)
• Claude Code memory documentation
• Agent Skills standard
• agentskills/agentskills
• vercel-labs/skills

See Also

• SDLC and Tooling
• Skills Ecosystem