Master AGENTS.md with this AI Agent Skill for Developers.
Keep docs under 60 lines to prevent instruction degradation and boost agent performance.
Minimalism
High-Signal
Agentic-Workflows
Documentation-as-Code
About This Skill
Optimize your AI workflows by enforcing a strict limit of under 60 lines for AGENTS.md. This skill helps you manage the 100-line maximum threshold to prevent instruction-following quality degradation.
Quick Start
1Create AGENTS.md at your project root
2Analyze your package manager and linter configs
3Add high-signal commands and references
Example Command
ln -s AGENTS.md CLAUDE.md
Core Capabilities
When to Use
Identify optimal moments to create, update, or audit agent documentation based on project drift.
File Setup
Automate the creation of AGENTS.md and the necessary CLAUDE.md symlinks.
Before Writing
Deeply analyze package managers, linters, and monorepo indicators before drafting content.
Writing Rules
Enforce a strict 'no filler' policy using headers, bullets, and code blocks.
Usage Examples
Before
AGENTS.md: 'Welcome to the project! We use pnpm. Here is a long list of everything we do...'
A concise pointer: 'See CONTRIBUTING.md for setup'.
SKILL.md
---
name: agents-md
description: This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation.
risk: unknown
source: community
---
# Maintaining AGENTS.md
AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.
## When to Use
- The user asks to create, update, or audit `AGENTS.md` or `CLAUDE.md`.
- The project needs concise, high-signal agent instructions derived from the actual toolchain and repo layout.
- Existing agent documentation is too long, duplicated, or drifting away from real project conventions.
## File Setup
1. Create `AGENTS.md` at project root
2. Create symlink: `ln -s AGENTS.md CLAUDE.md`
## Before Writing
Analyze the project to understand what belongs in the file:
1. **Package manager** — Check for lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `uv.lock`, `poetry.lock`)
2. **Linter/formatter configs** — Look for `.eslintrc`, `biome.json`, `ruff.toml`, `.prettierrc`, etc. (don't duplicate these in AGENTS.md)
3. **CI/build commands** — Check `Makefile`, `package.json` scripts, CI configs for canonical commands
4. **Monorepo indicators** — Check for `pnpm-workspace.yaml`, `nx.json`, Cargo workspace, or subdirectory `package.json` files
5. **Existing conventions** — Check for existing CONTRIBUTING.md, docs/, or README patterns
## Writing Rules
- **Headers + bullets** — No paragraphs
- **Code blocks** — For commands and templates
- **Reference, don't embed** — Point to existing docs: "See `CONTRIBUTING.md` for setup" or "Follow patterns in `src/api/routes/`"
- **No filler** — No intros, conclusions, or pleasantries
- **Trust capabilities** — Omit obvious context
Frequently Asked Questions
FAQ
What is the ideal document length for compatibility?
Target under 60 lines; never exceed 100 lines to ensure high instruction-following quality.
Who is the target audience for this skill?
Primarily AI Engineers, Developers, and anyone managing LLM-based agentic workflows.
How does this differ from standard README files?
Unlike READMEs, AGENTS.md is specifically optimized for machine readability and minimal signal-to-noise ratio.
Does it support different package managers?
Yes, it is designed to analyze and reference pnpm, yarn, npm, uv, poetry, and more.
What are the expected results of using this skill?
Reduced token usage, faster agent processing, and more accurate instruction adherence.
Discussion
Discussion
0 comments
U
On This Page
Trigger Phrases
Use these phrases to activate this skill in your AI coding assistant:
create AGENTS.mdupdate AGENTS.mdmaintain agent docsset up CLAUDE.mdaudit agent instructions
