Back to Blog

How to Write AI Agent Skills Any LLM Can Follow — The AGENTS.md Standard

AIAgents

Most teams building with AI agents hit the same wall: a skill that works perfectly in Claude Code breaks in Copilot, a workflow tuned for Codex confuses Gemini CLI. The fix isn’t rewriting everything for each platform — it’s writing agent instructions correctly from the start. That’s what AGENTS.md and SKILL.md solve.

What AGENTS.md Actually Is

AGENTS.md is an open, plain-Markdown format that gives any coding agent the context it needs to work in your project. Think of it as the README your AI Agent reads instead of your human contributors. It emerged in mid-2025 specifically to end the fragmentation of per-tool instruction files — one file, every runtime. Cursor, Codex, Copilot, Claude Code, Devin, Windsurf, and Gemini CLI all support it.

The format has no required fields. You write headings that make sense for your project — build steps, test commands, naming conventions, architectural constraints — and agents parse the natural language. The closest AGENTS.md in the directory tree takes precedence, so a mono-repo can have global instructions at root and tighter specs per subdirectory.

What AGENTS.md does not do is define capabilities. That’s SKILL.md’s job.

The SKILL.md Structure — One File, One Capability

Where AGENTS.md describes a project, SKILL.md describes what an agent can do. Every skill lives in its own directory with a SKILL.md at its root, and that file has two parts: YAML fron-tmatter and a Markdown instruction body.

The front-matter’s name and description fields are where most people go wrong. The agent decides whether to load a skill based on the description alone — before reading a single instruction. A vague description means the skill never activates. Write descriptions that specify when the skill applies and when it doesn’t. If you’re spending an hour debugging why a skill won’t trigger, it’s almost always the description, not the instructions.

The instruction body is standard Markdown: steps, conditionals, examples. Keep the main SKILL.md under 500 lines and move heavy reference material to a separate references/ subdirectory. The recommended ceiling is 5,000 tokens — beyond that, you’re paying inference costs without performance gains (LLM-generated context files already push costs up 20%+ compared to lean, human-curated ones).

Building a CSUITE Agent Manager

A single skill handles a single capability. A CSUITE Agent Manager handles many skills across many agents — it’s the orchestration layer that routes tasks to specialists and synthesizes their output.

The pattern works like this: the Manager agent holds a lightweight AGENTS.md that defines its routing logic, available sub-agents, and escalation rules. Each sub-agent (a docs agent, a security agent, a test agent) has its own SKILL.md scoped strictly to its domain. The Manager never executes domain work directly — it delegates, collects results, and decides next steps.

What separates a good Agent Manager from a brittle one is how it handles the unexpected. Production systems fail when the Manager over-specifies — trying to pre-plan every branch. Better designs let the Manager discover the task plan through collaboration: spawn a specialist, evaluate the result, decide whether to continue, escalate, or loop. This is the key distinction between a static orchestrator and a true Agent Manager.

Keep each sub-agent’s SKILL.md narrowly scoped. An agent that does too much has a description that triggers on too much — and you lose the predictability that makes the pattern worth building.

What to Get Right Before You Build

Three things matter most before writing your first skill: write AGENTS.md for humans first (if a human can’t follow it, an LLM won’t either), nail the SKILL.md description before the instructions, and keep the Manager agent’s routing logic explicit enough to audit. Skill authoring is still new enough that the tooling won’t catch your mistakes — the discipline has to come from the author.

The teams getting this right are treating AGENTS.md the way good engineers treat README.md: a living document that earns its maintenance cost by making every contributor — human or agent — faster from day one.

Further Reading

AI Disclosure

This document is drafted by an AI skill and is provided for informational and governance support purposes only. It does not constitute legal advice or a formal compliance determination. Do not publish or rely on this notice as a substitute for review by qualified legal counsel or a licensed compliance professional with jurisdiction-specific expertise.