# Agents Md Guidelines

> Guidelines for writing small, stable AGENTS.md files. Use when creating, refactoring, or reviewing AGENTS.md.

- Skill: `diegosouzapw/agents-md-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/agents-md-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/agents-md-guidelines/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/agents-md-guidelines

---


# AGENTS.md Guidelines

## Core Principles

- Keep root AGENTS.md as small as possible; it loads on every request.
- Use progressive disclosure: link to deeper docs for details.
- Prefer stable concepts over volatile paths or time-sensitive notes.
- Avoid “ball of mud” growth; don’t add rules for every mishap.
- Keep instructions concise; assume the agent already knows basics.

## Essentials Only

Root AGENTS.md should usually include:
- One-sentence project description
- Package manager if non-default
- Non-standard build/typecheck commands
- Pointers to deeper docs

## Progressive Disclosure

- Move language, testing, and workflow rules into separate docs.
- Link to those docs from AGENTS.md.
- Keep guidance domain-based, not file-path based.
- Avoid deep reference chains; link one level deep when possible.

## Staleness Rules

- Avoid exact file paths unless they are stable interfaces.
- Avoid dates or time-based instructions.
- Prefer capability descriptions over structure hints.

## Monorepo Guidance

- Use root AGENTS.md for shared rules.
- Use package-level AGENTS.md for package-specific conventions.
- Keep each level focused and minimal.

## Instruction Design

- Start with a TL;DR checklist for fast scanning.
- Include clear triggers and skip cases to prevent overuse.
- Provide ordered steps with explicit outputs.
- Use strict format rules with correct/incorrect examples.
- Add a decision tree for edge cases when needed.
- Include validation and debugging tips to reduce failure loops.
- Make naming conventions explicit.
- Define archive or completion criteria.
- Keep terminology consistent.

## Quality Checklist

- Description includes what + when, third-person.
- Root AGENTS.md is short and link-heavy.
- TL;DR + triggers + steps are present when needed.
- No duplicated guidance across files.
- Terminology is consistent.
- Examples are concrete and brief.
- Instructions fit an "instruction budget".