NetFabric/NetFabric.Numerics / .agents/skills/agents-md
agents-md
VerifiedAuthor 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| references/anatomy-and-discovery.md | markdown | 3.2 KB |
| references/authoring-workflow.md | markdown | 4.5 KB |
| references/quality-and-security.md | markdown | 2.2 KB |
| references/writing-style.md | markdown | 2.0 KB |
references/anatomy-and-discovery.md
View on GitHub# Anatomy & Discovery
## Placement
| Scope | Path | Applies To |
|-------|------|-----------|
| Repo-wide | `AGENTS.md` at repo root | Every file in the repo, unless overridden by a nested file |
| Subproject | `<package>/AGENTS.md` | That package/directory subtree only |
| Deeply nested | `<package>/<module>/AGENTS.md` | That module subtree only |
## Discovery & Precedence
Agents walk up from the file being edited to find the nearest `AGENTS.md`; the closest file wins on conflict (some tools also surface the root file for extra context, but precedence goes to the nearest). Explicit user chat instructions override every `AGENTS.md`, always. No required fields or schema — any heading structure is valid; agents parse plain text.
```mermaid
flowchart TD
A[Agent about to edit a file] --> B{AGENTS.md in this directory?}
B -- Yes --> C[Use it - nearest file wins]
B -- No --> D{At repo root?}
D -- No --> E[Move up to parent directory]
E --> B
D -- Yes --> F[No AGENTS.md applies]
C --> G[User chat instructions still override]
```
## Monorepo Nesting
```text
repo/
├── AGENTS.md # org-wide conventions: commit style, security, shared tooling
├── packages/
│ ├── api/
│ │ └── AGENTS.md # api-specific build/test/lint commands
│ └── web/
│ └── AGENTS.md # web-specific build/test/lint commands
└── infra/
└── AGENTS.md # IaC-specific conventions
```
Rules:
- Add a nested file only when a subproject's commands/conventions genuinely diverge from the root.
- A nested file should cover **deltas only** — don't repeat root-level content (PR title format, security rules) that already applies repo-wide.
- Large orgs ship many nested files (OpenAI's Codex repo has 88+); this scales better than one sprawling root file.
## Migrating Legacy Files
Many tools historically used their own filename. Consolidate onto `AGENTS.md` and keep a pointer file for backward compatibility:
```bash
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
```
For Claude Code, prefer a `CLAUDE.md` containing only Claude's `@`-import directive over a symlink — it survives zip downloads and Windows checkouts without symlink support. Ask the user whether Claude compatibility is needed before adding it:
```markdown
@AGENTS.md
```
If yes, pair this `CLAUDE.md` with every `AGENTS.md` in the repo, including nested ones — one `CLAUDE.md` + `@AGENTS.md` per directory that has its own `AGENTS.md`.
| Legacy File | Tool | Migration |
|-------------|------|-----------|
| `AGENT.md` | Various early adopters | Rename + symlink |
| `CLAUDE.md` | Claude Code | Pair with `@AGENTS.md` import (not a symlink) |
| `.cursor/rules` | Cursor | Fold content into `AGENTS.md`; Cursor also reads it natively |
| `.github/copilot-instructions.md` | GitHub Copilot | Keep both if repo targets multiple agents, or fold into `AGENTS.md` |
| `.aider.conf.yml` | Aider | Add `read: AGENTS.md` to point Aider at the shared file |
| `.gemini/settings.json` | Gemini CLI | Add `{ "context": { "fileName": "AGENTS.md" } }` |
Prefer one canonical `AGENTS.md` per directory scope; use symlinks or import directives rather than maintaining duplicate content across tool-specific files.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |