Skip to content

NetFabric/intelligentium / .agents/skills/agents-md

agents-md

Verified

Author and maintain AGENTS.md files — the open, tool-agnostic format for giving coding agents project context. Use when: creating AGENTS.md; writing an agent instructions file; root or nested AGENTS.md for monorepos; migrating CLAUDE.md, AGENT.md, .cursor/rules, or copilot-instructions.md to AGENTS.md; greenfield project setup before code exists; brownfield onboarding for an existing codebase; documenting build/test/lint commands, code style, PR/commit conventions, and security considerations for agents; AGENTS.md discovery and precedence rules. Works for any language, framework, or project size. DO NOT USE FOR: authoring SKILL.md skill files (use create-skill); APM package/plugin authoring (use apm-producer); language-specific style rules (use language skills e.g. csharp-best-practices).

AGENTS.md

A README for agents: plain Markdown, no required fields, read by 20+ coding agents (Codex, Cursor, Copilot, Aider, Gemini CLI, Windsurf, Devin, and more).

Quick Facts

FactDetail
LocationAGENTS.md at repo root; additional copies nested per package/subproject
DiscoveryAgent reads the nearest AGENTS.md up the directory tree from the file it's editing
PrecedenceClosest file to the edited file wins; explicit chat/user instructions override everything
FormatStandard Markdown, any headings, no schema to validate
ExecutionAgents run commands listed in it (tests, lint) and try to fix failures before finishing

Workflow Picker

flowchart TD
    A[Writing AGENTS.md] --> B{Code, CI, or docs already exist?}
    B -- No --> C[Greenfield workflow]
    B -- Yes --> D[Brownfield workflow]
    C --> E{≥2 packages?}
    D --> E
    E -- Yes --> F[Nest AGENTS.md per package]
    E -- No --> G[Single root AGENTS.md]
SituationUse
No code yet / scaffolding a new repoGreenfield workflow
Existing codebase, README/CI/CLAUDE.md already existBrownfield workflow
Monorepo with multiple packagesNesting rules
Migrating from AGENT.md, CLAUDE.md, .cursor/rules, copilot-instructions.mdLegacy migration

Core Principle

Never hardcode language, framework, or tool assumptions into an AGENTS.md — every instruction must reflect the target repo's actual, verified stack and commands, not a generic template left unfilled.

Run agent-markdown-best-practices over the content for compact, executable, agent-facing instructions. Then run markdown-best-practices for Markdown syntax and rendering hygiene.

Reference Files

FileLoad When
references/anatomy-and-discovery.mdDeciding where files live, how precedence works, or migrating from a legacy agent file
references/authoring-workflow.mdWriting a new AGENTS.md for a greenfield or brownfield project
references/quality-and-security.mdReviewing content quality, verifying commands, or covering security considerations
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall