AgentSkillsCN

agents-md-generator

在仓库根目录及嵌套模块目录中，采用渐进式披露的方式创建或更新最小化的 AGENTS.md 文件。无需假设固定的代理文件夹结构，即可在异构项目间灵活应用。

SKILL.md
--- frontmatter
name: agents-md-generator
description: Create or update minimal AGENTS.md files in the repository root and nested module directories using progressive disclosure. Works across heterogeneous projects without assuming any fixed agent folder structure.
compatibility: Filesystem-based coding agents with read/write access. Script execution optional.
metadata:
  author: Stanislav [MADTeacher] Chernyshev
  version: "1.0"

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

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

    If no local directory exists

    code
    Skill: agents-md-generator (external)

Never assume filesystem paths.