Get the FREE Ultimate OpenClaw Setup Guide →

agents-md-generator

Scanned
npx machina-cli add skill MADTeacher/mad-agents-skills/agents-md-generator --openclaw
Files (1)
SKILL.md
3.7 KB

AGENTS.md Generator (Root + Nested, Portable)

Goal

Maintain small, high-signal AGENTS.md files:

  • Root AGENTS.md — purpose of repository, navigation, universal toolchain, canonical commands, links to docs and skills.
  • Nested AGENTS.md — module/package purpose, local commands, module references.

Use progressive disclosure: keep AGENTS.md concise; push details to docs or skills.

Skill location (agent-specific)

  • Do NOT assume .agents/ or any fixed directory exists.
  • Skills may live:
    • inside the repository (embedded),
    • or in an external/global skill library (external).
  • If referencing local skills, first detect an existing skill root already used by the project.
  • If no local skill directory exists — reference skills by name only (external).
  • Never create hidden agent directories just to store skills.

When to run

Run this skill when:

  • AGENTS.md is missing, bloated, contradictory, or outdated.
  • A new package/service/module appears.
  • Repository structure changes (monorepo growth or split).
  • Teams want consistent agent context across diverse stacks.

Workflow (Deterministic)

1. Discover repository shape

  • Identify repository root (git root if available).
  • Detect language/tool markers:
    • package.json, pnpm-workspace.yaml
    • go.mod, go.work
    • pyproject.toml
    • Cargo.toml
    • pubspec.yaml
    • pom.xml, build.gradle
  • Locate docs/, README.md, existing AGENTS.md.

2. Detect module boundaries

Create nested AGENTS.md if directory:

  • Contains independent build/package manifest
  • OR represents deployable/service unit (apps/, services/, packages/)
  • AND differs in stack/toolchain from parent scope

3. Generate/Update Root AGENTS.md

Constraints:

  • Ideal size: ≤ 60 lines
  • Must include:
    • One-sentence repository purpose
    • Primary toolchain/package manager
    • Canonical commands (if non-standard)
    • Links to docs
    • Instruction to read nested AGENTS.md when inside modules
    • Optional skill references (adaptive: local or external)

4. Generate/Update Nested AGENTS.md

Constraints:

  • Ideal size: ≤ 40 lines
  • Must include:
    • One-sentence module purpose
    • Module-specific commands
    • Local documentation references
    • Optional skill references (adaptive)

5. Progressive Disclosure Rules

  • Do not embed style guides, CI policies, or architecture details.
  • Prefer links to:
    • docs/STYLE_GUIDE.md
    • docs/ARCHITECTURE.md
    • external or local skills
  • Avoid “always/never” rules unless critical for correctness/security.

6. Safety / Correctness Gates

  • Never invent commands.
  • Infer commands from:
    • package scripts
    • Makefile
    • CI configuration
    • README
  • If uncertain → write: “Known commands: see <file>”
  • Preserve critical warnings (security, secrets, deployment).

Output Contract

Create or update only:

  • <repo_root>/AGENTS.md
  • <module_dir>/AGENTS.md

Do not create agent configuration folders.

Skill Referencing Strategy

When adding skill references inside AGENTS.md:

  1. If local skill directory detected

    See: <detected-skill-root>/<skill-name>/SKILL.md

  2. If no local directory exists

    Skill: agents-md-generator (external)

Never assume filesystem paths.

Source

git clone https://github.com/MADTeacher/mad-agents-skills/blob/main/agents-md-generator/SKILL.mdView on GitHub

Overview

Generates concise AGENTS.md files at repository root and nested module directories using progressive disclosure. It works across heterogeneous projects without assuming fixed agent folders by detecting repo shape, module boundaries, and linking to docs and skills.

How This Skill Works

The tool scans the repository to identify the root and typical manifests, then determines module boundaries. It then generates or updates root and nested AGENTS.md files following progressive disclosure rules, referencing local or external skills when available and avoiding hidden directories.

When to Use It

  • AGENTS.md is missing, bloated, contradictory, or outdated.
  • A new package/service/module appears in the repo.
  • Repository structure grows into a monorepo or splits into components.
  • Teams need a consistent agent context across diverse stacks.
  • A module uses a different tech stack than its parent and requires its own AGENTS.md.

Quick Start

  1. Step 1: Run the generator at repo root to detect structure and existing AGENTS.md files.
  2. Step 2: Review proposed root and nested AGENTS.md content for accuracy and brevity.
  3. Step 3: Commit AGENTS.md updates and push; ensure module docs and skill references resolve.

Best Practices

  • Keep AGENTS.md concise: root ≤ 60 lines, nested ≤ 40 lines.
  • Prefer links to docs and to external or local skills rather than embedding long policies.
  • If a local skill directory is detected, reference it as 'See: <detected-skill-root>/<skill-name>/SKILL.md'.
  • Do not create hidden agent directories; avoid filesystem assumptions beyond detection.
  • Infer commands from package scripts, Makefiles, CI configs, or README; if uncertain, use 'Known commands: see <file>'.

Example Use Cases

  • Root AGENTS.md created for a JavaScript monorepo with multiple packages and a shared toolchain.
  • Nested AGENTS.md added for a Python service with its own package manifest and local docs.
  • Root and module AGENTS.md updated after adding a new microservice in a polyglot repo.
  • Local skill references detected; AGENTS.md points to See: local-skill-root/skills/AGENTS.md.
  • External skills referenced when no local skill directory exists, maintaining consistency.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗