agents-md-generator

What this skill does

# AGENTS.md Generation Capability

This skill enables the agent to generate `AGENTS.md` files that serve as contributor guides for AI agents working on a codebase.

## Core Capability

- **Function**: Analyze repository structure and generate or update a standardized `AGENTS.md` document
- **Output Format**: Markdown file with structured sections
- **Character Limit**: Dynamic, based on repository LOC (Lines of Code)
- **Monorepo Support**: Automatically detects monorepo structures and generates hierarchical documentation (Root + Packages)
- **Update Support**: Refreshes only standard sections in an existing `AGENTS.md`, preserving user-defined custom sections

## Output Sections

### Single Repo / Package Document (5 Sections)
For single repositories or individual packages in a monorepo:

- **Overview**: 1-2 sentence project description (abstract, no tool/framework lists)
- **Folder Structure**: Key directories and their contents
- **Core Behaviors & Patterns**: Cross-cutting patterns traced through full flows — error propagation chains, state lifecycle transitions, cross-boundary wiring mechanisms, resilience/recovery strategies, shared resource management. Discovered via multi-phase analysis: surface idiom detection, then deep tracing across layers.
- **Conventions**: Naming, code style, API/interface design conventions (callback naming, return value shapes, method responsibility splitting), configuration/registration structure, boundary conventions (error flattening, schema drift absorption, containment rules), component composition patterns.
- **Working Agreements**: Rules for agent behavior and communication

### Monorepo Root Document (3 Sections)
For the root of a monorepo structure:

- **Overview**: 1-2 sentences describing the monorepo's purpose
- **Folder Structure**: High-level map of apps, packages, and shared configs
- **Working Agreements**: Common working agreements applicable to all packages

## Operation Modes

### Generate vs Update

- **Generate**: Creates a new `AGENTS.md` from scratch (default when no `AGENTS.md` exists)
- **Update**: Refreshes standard sections in an existing `AGENTS.md` while preserving custom sections. See [./references/update_strategy.md](./references/update_strategy.md) for detailed workflow and section matching rules.

The agent automatically selects the appropriate mode based on whether an `AGENTS.md` file already exists at the target location.

### Generation Modes (Monorepo)

Supports three modes: **All** (root + all packages, default), **Root Only**, and **Single Package**. See [./references/monorepo_strategy.md](./references/monorepo_strategy.md) for detailed strategy and mode selection criteria.

## Execution Workflow

Run these steps in order. Each step has a fixed output that the next step depends on; skipping ahead produces wrong character budgets, unmatched update sections, or missed monorepo packages. The bundled scripts under `./scripts/` make the deterministic steps reproducible — invoke them rather than re-deriving the logic each run.

### Step 1 — Decide Mode

1. Check whether `AGENTS.md` exists at the target location. Present → **Update**. Absent → **Generate**.
2. Run monorepo detection at the repo root:

   ```bash
   python ./scripts/detect_monorepo.py <repo_root>
   ```

   Output: `{is_monorepo, markers}`. If `is_monorepo` is true, choose **All / Root Only / Single Package** per [./references/monorepo_strategy.md](./references/monorepo_strategy.md). Otherwise treat the repo as a single document.

### Step 2 — Measure LOC and Allocate Budget

For each target document (single repo, or root + each package), run:

```bash
python ./scripts/loc_to_limit.py <target_directory>
```

Output: `{loc, scale, character_limit}`. If the script reports `tokei` is missing, surface its install message and stop — do not estimate LOC by hand. Allocate `character_limit` across sections using the proportions in [./references/loc_measurement.md](./references/loc_measurement.md) (Section Budget Allocation).

### Step 3 — Build Stack Context

Before pattern/convention analysis, read the package manifests at the document's scope (root or per package) per [./references/read_only_commands.md](./references/read_only_commands.md) > Dependency Discovery. Skip lock files. Use this stack context to focus Step 4 on relevant frameworks rather than searching blindly.

### Step 4 — Analyze the Repository

Run the multi-phase analysis defined in [./references/agents_md_template.md](./references/agents_md_template.md):

1. **Phase 1** — Stack & Surface Discovery (recurring idioms in 3+ files, project-specific abstractions).
2. **Phase 2** — Deep Tracing across layers (error propagation, wiring, state lifecycle, failure paths, centralized delegation).
3. **Phase 3** — Validation (each pattern present in 3+ locations, accounting for cross-layer flows).

If Serena MCP is available, prefer its read-only symbol tools (`find_symbol`, `find_referencing_symbols`, `get_symbols_overview`, etc.) over `rg` / `grep` / `find` — symbolic queries are more accurate for caller tracing and cross-layer flows. See [./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp](./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp).

Run this analysis in the current context only. **Do not delegate to subagents** — Phase 3 cross-pattern validation and section-level budget tracking require a unified view (see [Scope Boundaries](#scope-boundaries) > Single-Context Execution).

Stay within each section's character budget from Step 2. Document only patterns/conventions actually observed.

### Step 5 — Assemble (Generate) or Splice (Update)

- **Generate**: Emit the document using the structure in [./references/agents_md_template.md](./references/agents_md_template.md) (5 sections for single repo / package, 3 for monorepo root). Use [./references/working_agreements.md](./references/working_agreements.md) for the Working Agreements section.
- **Update**: Run the section parser on the existing file:

  ```bash
  python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type single_repo
  ```

  (Use `--doc-type monorepo_root` for the monorepo root document.) The output marks each `## ` heading as `is_standard` (managed) or not (preserved). Replace **only** the standard sections' bodies; keep custom sections, the file title, and any preamble before the first `##` unchanged. Insert any `missing_standard` heading at its numbered position relative to other standard sections. Full reassembly rules: [./references/update_strategy.md](./references/update_strategy.md).

  If the existing document type no longer matches the repo (e.g., a single repo became a monorepo), force full regeneration instead of update.

### Step 6 — Verify and Write

Before writing, confirm:

- Total length is within `character_limit`; no section exceeds its budget.
- None of the [Anti-Patterns](./references/agents_md_template.md#anti-patterns-excluded-content) appear (no Common Commands, run/test/build/deploy instructions, IDE/tooling settings, etc.).
- For Update mode: every standard section body was rebuilt from its managed source, not reused because the old wording appeared acceptable.
- For Update mode: scan only managed standard sections for stale standing work-agreement wording. Fail verification if managed content still contains `Keep edits minimal`, `Minimal changes`, `preserve public APIs`, `existing plugin behavior`, or `avoid unnecessary abstraction`; custom sections may keep any user-owned wording.
- For Update mode: every preserved custom section is byte-for-byte identical to the original.

Then write with the Edit/Write tool. For Monorepo with mode = **All**, repeat Steps 2–6 per target package after handling the root.

## Tools

This skill uses the following read-only tools for repository analysis. See [./references/read_only_commands.md](./references/read_only_commands.md) for detailed usage patterns.

- **Sere