---
name: agents-md-mapper
description: This skill should be used when creating, refreshing, or validating a repository `AGENTS.md` so it stays concise, current, and grounded in repository evidence. Use when `AGENTS.md` is missing or stale, after refactors or tooling changes, when new docs become the system of record, or when adding lightweight drift checks.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(git:*)
  - Bash(ls:*)
hard-guards:
  - Treat `AGENTS.md` as a map, not a dump
  - Update only from repository evidence: files, docs, CI, commands, and git history
  - Prefer stable paths and exact commands over prose-heavy explanation
  - Keep `AGENTS.md` roughly under 100 lines unless repo complexity clearly requires more
  - Omit weak or speculative claims
  - Never include secrets, tokens, credentials, or environment values
---

# AGENTS.md Mapper

## Overview

Maintain a concise, current `AGENTS.md` for a repository as the codebase changes. Treat the file as a navigational map for future coding agents: show where to start, where important things live, how to validate changes, and which deeper docs outrank the map.

## When to Use

- Create a new `AGENTS.md` for a repository that does not have one
- Refresh an existing `AGENTS.md` that may be stale after refactors, path moves, package splits, or architecture changes
- Update the map after tooling, tests, CI, docs, or ownership signals changed
- Point `AGENTS.md` at new architecture docs, runbooks, or generated references that became the source of truth
- Add lightweight checks that detect drift between `AGENTS.md` and repository reality

## Core Contract

### 1. Keep the map compact

- Prefer roughly 90 to 100 lines
- Prefer bullets over paragraphs
- Prefer concrete paths and commands over abstract advice
- Link to deeper docs instead of copying them

### 2. Treat repository evidence as the source of truth

- Read the repository tree before writing claims about structure
- Read actual config files before listing commands
- Read CI workflows before describing validation
- Read docs and architecture references before summarizing boundaries
- Read recent git history before carrying forward old paths or retired modules

### 3. Optimize for agent legibility

- Surface entry points, domain boundaries, and validation commands first
- Make the navigation order obvious
- Remove stale or duplicated sections aggressively
- Normalize heading order so future updates stay mechanical

### 4. Omit unsupported detail

- If evidence is weak, omit the claim
- If a detail is volatile, point to its source doc instead of embedding it
- If two docs disagree, prefer the one supported by current code and CI

## Inputs to Inspect

Inspect repository evidence, not guesswork:

- Current top-level tree and major subdirectories
- Key top-level files such as `README`, `pyproject.toml`, `package.json`, `Cargo.toml`, `Makefile`, `justfile`, or task runner configs
- Existing `AGENTS.md`, if present
- `ARCHITECTURE.md`, `docs/`, runbooks, plans, references, and generated indexes
- CI workflows and automation config
- Recent git history, especially merges, path renames, retired modules, and tooling changes
- Ownership signals such as `CODEOWNERS`, package manifests, and boundary-enforcement config

## Workflow

### Step 1: Discover repository shape

- Collect the top-level tree and major subdirectories
- Identify package roots, module roots, and major domain folders
- Locate docs indexes, architecture docs, and runbooks
- Capture build, test, lint, and run entrypoints from real config files

### Step 2: Read the current map and deeper docs

- Open `AGENTS.md` if it exists
- Open the main onboarding docs first: `README`, architecture docs, and docs indexes
- Open the exact files that define task runner commands and CI gates
- Note which docs already serve as the system of record

### Step 3: Inspect recent change signals

- Review recent git history for renamed paths, new packages, retired directories, and workflow changes
- Check whether new docs or generated references replaced older explanations
- Check whether CI or task runners added or removed validation steps

### Step 4: Compare map versus reality

- Verify that listed paths still exist
- Verify that listed commands still exist and still match task runner or CI usage
- Verify that architecture or package boundaries still match current layout
- Verify that linked docs still exist and remain the best source of truth

### Step 5: Rewrite for compression and clarity

- Keep only high-value navigational content
- Collapse repeated guidance into one canonical section
- Replace prose-heavy explanations with stable file paths and exact commands
- Remove outdated paths, retired tools, and stale historical detail

### Step 6: Validate before finalizing

- Re-check every path and command
- Remove duplicate or unsupported claims
- Confirm the file remains short, scan-friendly, and grounded in current evidence

## What to Put in `AGENTS.md`

Include these sections when repository evidence supports them:

- Project overview
- Where to start
- Repository map
- Build, test, lint, and run commands
- Architecture or package boundaries
- Key docs and sources of truth
- Change rules or contribution guardrails
- Validation checklist

Exclude these unless they directly change navigation or implementation behavior:

- Long architectural essays
- Full style guides already documented elsewhere
- Exhaustive dependency lists
- Historical detail that does not affect current navigation
- Issue triage policy that does not change implementation work

## Decision Rules

- If a section grows past a few bullets, move detail to `docs/` or another source doc and link to it
- If commands differ between docs and CI, prefer the version backed by current config
- If the repository already has a strong docs index, make `AGENTS.md` point to it rather than restating it
- If a repo has no evidence for ownership or architecture boundaries, do not invent them

## Output Modes

Produce one of these outputs:

- A fresh `AGENTS.md`
- A focused patch for the existing `AGENTS.md`

Use the compact outline in `references/agents-md-outline.md` as a starting point when the repository supports those sections.

## Validation Checklist

- Every listed path exists
- Every listed command is defined in current repo config or CI
- Every linked source-of-truth doc exists
- Stale headings and duplicate sections are removed
- The file stays compact and navigable
- No secrets or environment values appear in the file

## Recommended Follow-Up Checks

When automation is requested, add lightweight drift checks such as:

- Fail if a linked path in `AGENTS.md` no longer exists
- Fail if a listed command disappears from CI or task runner config
- Flag missing references to new top-level domains after major tree changes
- Flag stale sections after large refactors or package moves

## Success Criteria

Consider the skill successful when:

- `AGENTS.md` is short and easy to scan
- Every listed path and command matches the current repository
- The file points to deeper sources of truth instead of copying them
- Stale guidance is removed
- Another coding agent can use `AGENTS.md` as a reliable repository map