home / skills / jmerta / codex-skills / agents-md

agents-md skill

safe

This skill creates or updates root and nested AGENTS.md files to document module maps, cross-domain workflows, and optional feature maps for a monorepo.

npx playbooks add skill jmerta/codex-skills --skill agents-md

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.9 KB

---
name: agents-md
description: Create or update root and nested AGENTS.md files that document scoped conventions, monorepo module maps, cross-domain workflows, and (optionally) per-module feature maps (feature -> paths, entrypoints, tests, docs). Use when the user asks for AGENTS.md, nested agent instructions, or a module/feature map.
---

# AGENTS.md builder

## Goal
Add lightweight, scoped guidance for an AI agent (and humans) by placing AGENTS.md files at key directory boundaries:
- root: cross-domain guidance + a module map (for monorepos)
- nested: tech-specific instructions for each component/module
- optional: feature maps at the module level

Optimize for concise and precise instructions (short bullets, minimal prose). Link to docs for depth.

## Inputs to ask for (if missing)
- Is this a monorepo (multiple independently-built modules) or a single project?
- Repo layout: where backend, frontend, docs, infra live; list the major modules/subprojects.
- Cross-domain workflows to document (e.g., frontend calling backend API, auth flow, shared types, local dev).
- If you want feature maps: top 5-15 user-facing features (names) and which module owns them.
- Any rules about MCP usage to capture in root AGENTS.md (allowed servers/tools, safety constraints).
- Any hard rules (do not touch X, required commands, style rules).

## Where to put AGENTS.md (heuristics)
Create AGENTS.md at:
- repo root (global rules + module map + cross-domain workflows)
- each major component/module root (e.g., `backend/`, `frontend/`, `docs/`, `infra/`)
- any subdirectory that has different conventions, ownership, or high risk (payments, auth, data migrations)

Avoid placing AGENTS.md too deep unless there is a real boundary; too many files become noise.

## Workflow (checklist)
1) Inventory the repo
   - List top-level directories and build files (Gradle/Maven, Node/Next, docs site).
   - Identify the natural "component roots" and any critical submodules.
2) Draft root `AGENTS.md`
   - State global rules only (things that apply everywhere).
   - If monorepo: add a module/subproject map (not a feature map) and links to each nested AGENTS.md.
   - Keep tech-specific instructions out of root; push them into the owning module's AGENTS.md.
   - Docs: do not open/read `docs/` by default; consult only when asked or required.
   - Add cross-domain workflows (how modules connect): frontend <-> backend API, auth/session, contract location (OpenAPI/GraphQL), "run together" local dev.
   - Add cross-repo verification guidance: where to run per module + prereqs; quiet first run; re-run narrowed failures with verbose logs when debugging.
3) Draft nested AGENTS.md per component
   - Put tech-specific instructions in the module that owns them:
     - Backend: how to run, test, migrate DB; key modules and entrypoints.
     - Frontend: how to run, build, test; env vars; key routes/areas.
     - Docs: docs structure, where to add ADRs/runbooks, how to preview/build docs.
4) Build maps (as needed)
   - If monorepo: module map goes in root (use `references/module-map-format.md`).
   - Feature maps should live in the owning module AGENTS.md (use `references/feature-map-format.md`).
5) Verify consistency
   - Ensure guidance does not conflict between parent/child scopes.
   - Keep each AGENTS.md short and actionable; move long detail into docs under `docs/`.

## Templates
Use these templates:
- Root + module AGENTS.md: `references/agents-template.md`
- Module map format: `references/module-map-format.md`
- Feature map table format (per module): `references/feature-map-format.md`
- Suggested `docs/` layout (Spring + Next): `references/docs-structure.md`

## Deliverable
Provide:
- Root `AGENTS.md` (if requested) with module map and cross-domain workflows.
- Nested `AGENTS.md` per component/module with tech-specific guidance.
- Optional feature map tables per module (if requested).
- A list of files created/updated and any open questions.

Overview

This skill creates or updates AGENTS.md files that document scoped conventions, a monorepo module map, cross-domain workflows, and optional per-module feature maps. It produces a root AGENTS.md for global rules and nested AGENTS.md files for component-specific instructions so agents and humans can act consistently. Deliverables include created/updated files and any open questions for the repo owner.

How this skill works

The skill inventories the repository to identify component roots and critical submodules, then drafts a concise root AGENTS.md with global rules and a module map (for monorepos). It generates nested AGENTS.md files at each component boundary containing tech-specific run/test/build/migration guidance and optional feature maps that map features to paths, entrypoints, tests, and docs. The output emphasizes short bullets and links to deeper docs rather than long prose.

When to use it

You need a single source of agent-facing conventions at repo boundaries.
Onboarding agents or humans to a monorepo with many modules.
When documenting cross-domain workflows like frontend↔backend, auth, or shared types.
Before automating agent tasks that touch multiple components (deploy, test, migrate).
To add per-module feature maps for targeted agent actions and testing.

Best practices

Put a root AGENTS.md with only global rules and a module map; keep tech specifics in module AGENTS.md.
Create module AGENTS.md at natural component roots (backend/, frontend/, infra/, docs/) and for high-risk dirs (auth, payments).
Keep guidance short: bullets, commands, file paths, and links to docs for details.
Avoid too many nested AGENTS.md files; prefer one per ownership boundary to reduce noise.
Include cross-domain workflows and where contract definitions (OpenAPI/GraphQL) live.

Example use cases

Generate root AGENTS.md for a monorepo with frontend/, backend/, and infra/ plus a module map linking to nested AGENTS.md.
Add backend/AGENTS.md describing how to run, test, migrate DB, key entrypoints, and command snippets.
Add frontend/AGENTS.md listing dev server steps, env vars, key routes, and build/test commands.
Produce feature maps in a module AGENTS.md mapping top user features to code paths, tests, and docs.
Audit repo to produce a files-changed list and open questions for missing inputs (monorepo status, feature list).

FAQ

Do I always need a root AGENTS.md?

Yes for any repo with cross-domain concerns or multiple modules; a single-project repo can omit module map but still benefit from a root file with global rules.

Where should feature maps live?

Feature maps belong in the owning module's AGENTS.md so they stay close to code and ownership.