agents-md-generator

Files (42)

• LICENSE
• SKILL.md
• content-quality-evals.json · evals/
• content-quality-rubric.json · evals/
• agents_md_template.md · references/
• content_quality.md · references/
• loc_measurement.md · references/
• monorepo_detection.md · references/
• monorepo_strategy.md · references/
• plain_language.md · references/
• read_only_commands.md · references/
• update_strategy.md · references/
• working_agreements.md · references/
• detect_monorepo.py · scripts/
• git_ownership_signals.py · scripts/
• loc_to_limit.py · scripts/
• parse_sections.py · scripts/
• test_detect_monorepo.py · scripts/
• test_parse_sections.py · scripts/
• agents-v1-test.patch · updates/2026-02-25-json-template-formatting-review/
• agents-v2-test.patch · updates/2026-02-25-json-template-formatting-review/
• no-agents-test.patch · updates/2026-02-25-json-template-formatting-review/
• review.md · updates/2026-02-25-json-template-formatting-review/
• review_en.md · updates/2026-02-25-json-template-formatting-review/
• review.md · updates/2026-03-11-json-query-explanation-review/
• review_en.md · updates/2026-03-11-json-query-explanation-review/
• benchmark.md · updates/2026-03-21-claude-skill-2_0-apply/
• result-A-no-agents.md · updates/2026-05-07-json-query-explanation-review/
• result-B-old-agents.md · updates/2026-05-07-json-query-explanation-review/
• result-C-new-agents.md · updates/2026-05-07-json-query-explanation-review/
• review.md · updates/2026-05-07-json-query-explanation-review/
• review_en.md · updates/2026-05-07-json-query-explanation-review/
• changes.patch · updates/2026-06-10-adversarial-review-hardening/
• review.md · updates/2026-06-10-adversarial-review-hardening/
• review_en.md · updates/2026-06-10-adversarial-review-hardening/
• agents-after.md · updates/2026-09-07-jetbrains-jsoninja-live-test/
• agents-before.md · updates/2026-09-07-jetbrains-jsoninja-live-test/
• agents.patch · updates/2026-09-07-jetbrains-jsoninja-live-test/
• review.md · updates/2026-09-07-jetbrains-jsoninja-live-test/
• run.json · updates/2026-09-07-jetbrains-jsoninja-live-test/
• README.md · updates/
• README_en.md · updates/

SKILL.md (first lines)

# 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 boundaries and generate or update a standardized `AGENTS.md` document
- **Output Format**: Markdown file with structured sections
- **Writing Goal**: Reader-centered guidance informed by ISO 24495-1:2023 plain language principles: contributors can find the relevant guidance, understand the verified contract, and use it for their next change
- **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 a marked, managed `AGENTS.md`, preserving user-defined custom sections. Unmarked files require a concrete change preview and one-time adoption confirmation; files without matching standard headings require an explicit full-regeneration request

## Output Sections

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

- **Overview**: 1-2 sentence project description (abstract, no tool/framework lists)
- **Ownership Map**: Optional, evidence-backed map split into stable ownership boundaries and active change routes — entry points, state owners, behavior decision points, external surfaces, contracts/side effects, verification anchors, and recent history-informed routes. Omit this section when the repository does not expose stable boundaries or active routes worth documenting; never invent ownership just to fill the template.
- **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 (2-3 Sections)
For the root of a monorepo structure:

- **Overview**: 1-2 sentences describing the monorepo's purpose
- **Ownership Map**: Optional map split into stable package-level responsibility boundaries and active cross-package change routes. At monorepo roots, package names plus manifests, public exports, README text, dependency direction, and recent confirmed change clusters can establish enough evidence; omit the section when the root exposes only an uninformative package list.
- **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 managed `AGENTS.md` while preserving custom sections. A valid management marker establishes enrollment in this workflow; matching headings identify replacement candidates, not authorship. Unmarked files need one-time adoption confirmation after a concrete preview; zero matching headings require an explicit full-regeneration request. See [./references/update_strategy.md](./references/update_strategy.md) for the marker contract and adoption workflow.

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 candidate** (subject to the management check below). Absent → **Generate**.
2. Run monorepo detection at the repo root:

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

   Output: `{is_monorepo, markers}`. A `true` result is provisional: discover the actual packages per [./references/monorepo_detection.md](./references/monorepo_detection.md). If fewer than 2 packages are found, treat the repo as a single document despite the marker. Otherwise choose **All / Root Only / Single Package** per [./references/monorepo_strategy.md](./references/monorepo_strategy.md). If `is_monorepo` is false, treat the repo as a single document.

3. Before LOC measurement or deep analysis, run `python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type <single_repo|monorepo_root>` for each existing target. `management_status` is `managed`, `unmarked`, or `invalid`; `generated_doc_type` records the valid marker's original document type or is null. Invalid markers stop automatic updating. Resolve the original type in the next item before applying the heading-count gate: unmarked files with matching standard headings may proceed to preparation of an adoption preview, but not writing; zero matched headings under the original type require an explicit full-regeneration request. A matching heading alone never authorizes a write.
4. Compare a valid `generated_doc_type` with the current target type. When they differ, rerun the parser with the original type to identify the original managed and custom sections before preparing full regeneration. For an unmarked file, infer its original type from distinctive standard headings (`## 3. Working Agreements` versus `## 3. Core Behaviors & Patterns` / `## 5. Working Agreements`); ask which original type to use if these conflict or are insufficient. Preserve original custom sections and obtain confirmation of the concrete type-transition preview before overwriting.
5. For package documents, check whether the repository-root `AGENTS.md` exists. If it does, reference its actual relative path. If it does not, include the common working agreements directly in the package document plus any discovered package-local verification command. Do not create a root file for a Single Package request. In All mode, recheck after the root has been handled.

### 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. Use the proportions in [./references/loc_measurement.md](./references/loc_measurement.md) as initial section allocations, then redistribute capacity according to verified content. Only the combined preamble and managed sections have a hard character limit; the section proportions are not independent ceilings.

### 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

Read [./references/content_quality.md](./references/content_quality.md) before analysis. Keep a compact internal record of decision-relevant facts, their current source evidence, and their intended destination. In Generate mode, discover these facts from source. In Update mode, also extract important facts from the old analysis-derived managed sections as inspection leads, reconfirm them against current source, and discover what the old document missed. The old document is not evidence of current behavior, and the working record is not a new output section.

For selected important behaviors, inspect direct implementing helpers until applicable choices, guard/bypass paths, recovery outcomes, state lifetime, ownership/cleanup conditions, and actual recipients are established. Save that compact relationship record in a temporary scratch file outside the target repository before drafting. A feature or helper name by itself does not close source tracing. Recent history affects active-route classification, not whether a currently verified safety contract is retained.

Before history-driven prioritization, build the coverage table from documented capabilities and authoritative registrations/public surfaces. In Update mode, also account for every old managed Stable boundary, Active route, and core flow. Confirm each row's current owner/consumer and selection or evidence-based exclusion. Trace selected rows from `open` to `closed` using actual implementing files and symbols, including each behavior-changing stage of a pipeline. A history window with no changes cannot exclude a live hook, migration, or safety condition.

For **Update mode**, use git history as an ownership-discovery signal before deep source tracing:

1. Prefer changes since the last skill-generated `AGENTS.md` update for the target document. If no reliable update anchor exists, default to roughly the last 3 months and adjust by repository activity.
2. Run the bundled high-churn signal helper before manually expanding git history:

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

   If a reliable update anchor exists, pass it with `--anchor <commit-ish>`. The script emits compact Markdown-KV to minimize context use.
3. Start with commit metadata and changed paths only. Do not read broad diffs by default.
4. Look for changed-path clusters, repeated co-change patterns, renames/moves, deleted paths, and high-churn boundary files.
5. Use history to decide where to inspect next, not what to document. Add an `Ownership Map` boundary only when current code or documented contracts confirm it.
6. Do not persist timeline summaries such as "earlier focus" or "current focus" in `AGENTS.md`. Report them only in the user-facing summary unless the transition is currently represented in code as a live migration or compatibility boundary.

See [./references/read_only_commands.md#git-history-signals-update-mode](./references/read_only_commands.md#git-history-signals-update-mode) for token-safe git commands and expansion rules.

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 (prefer patterns present in 3+ locations, accounting for cross-layer flows; also retain a single verified critical boundary that governs safe work).

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).

Document only patterns/conventions actually observed. Preserve necessary entry points, behavior-changing alternatives, exception/fallback conditions, lifecycle obligations, and compatibility effects. If a section needs more than its initial allocation, redistribute unused capacity within the total limit rather than deleting these facts. Apply the compression order in the content-quality reference.

If optional `## 2. Ownership Map` has no evidence-backed content, omit the section and keep later section numbers unchanged. Section numbers are update-mode identifiers; never renumber `Core Behaviors & Patterns`, `Conventions`, or `Working Agreements` to close the gap. When evidence exists, split Ownership Map content into `Stable Ownership Boundaries` for the durable safety boundaries the previous single-list Ownership Map would have documented, and `Active Change Routes` for recent history-informed routes confirmed against current code. Treat `Active Change Routes` as additive update-mode context, not as a replacement or filter for stable boundaries. Stable bullets are full change-routing rules; Active bullets are parent-linked or cross-boundary delta routes. Do not restate the parent Stable boundary's broad owner, contract, or verification in Active. If no meaningful delta remains after removing inherited Stable details, omit the Active route. Do not impose a bullet-count limit beyond the section character budget.

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

Read [./references/plain_language.md](./references/plain_language.md) before drafting. Write generated section bodies for a contributor who knows the project's programming language but does not yet know its local owners, terms, or contracts. Apply the same writing guidance to fresh managed bodies in Update mode; preserve custom sections and existing preamble bytes under the update contract. This is an output-writing pass, not a new section or a new standing rule for future agent responses.

From buYoung/skills, MIT.

More from buYoung/skills