AGENTS.md vs. Skills: How to Actually Steer a Coding Agent

Teams configuring coding agents are accumulating a new category of technical debt: instruction files that feel authoritative but whose actual effect on agent behavior has never been measured.

The Framework

AGENTS.md is a markdown file at the repository root that agents read at session start. It’s an open format with backing from OpenAI and Google — a universal header for agent context covering build commands, code style, repository layout, and any conventions that apply to nearly every task. Think of it as the floor: almost every project benefits from one, and it should be lean enough that agents read it fully without context pressure.

Skills are modular instruction bundles loaded on-demand. A skill contains task-specific instructions — a multi-step release checklist, a framework migration guide, a review rubric for a specific directory — that the agent retrieves only when the task requires it. Skills prevent context waste by not loading large, situational guidance into every session.

When to Use Each

Use AGENTS.md for:

• Build and test commands that apply to every task
• Repository layout and navigation conventions
• Code style rules that apply universally
• Security and compliance constraints that must always be active

Use Skills for:

• Multi-step release or deployment procedures
• Framework-specific migration workflows
• Review rubrics for specific components or file types
• Any guidance that’s large, procedural, or only relevant to a subset of tasks

Most teams that have thought about this use both: a lean AGENTS.md for universal facts and skills for specialized procedures. The question of which format isn’t the interesting one.

Where It Doesn’t Apply

The critical insight from CircleCI’s analysis: instructions don’t guarantee compliance. Three empirically observed patterns complicate any instruction-based configuration approach:

1. Compliance degrades as context windows fill: Agents that follow instructions correctly on short tasks start skipping steps when the context window is near capacity
2. Phrasing and placement affect adherence: The same instruction can produce different compliance rates depending on where in the file it appears and how it’s worded
3. More instructions can reduce compliance: An overstuffed AGENTS.md or too many skills loaded simultaneously can reduce overall adherence below what a minimal configuration achieves

The practical implication: the decision between AGENTS.md and skills is secondary to the question of whether your configuration actually changes agent behavior in measurable ways.

Source: CircleCI Engineering

Content created with AI assistance and reviewed for accuracy.