agents-md-generator

What this skill does

# AGENTS.md / CLAUDE.md Generator

## Overview

This skill helps you generate comprehensive instruction files (AGENTS.md with optional CLAUDE.md compatibility) that teach AI coding agents how to work effectively in your project. It combines automatic project scanning with interactive questions to create tailored guidelines.

**When to use this skill:**
- Setting up a new project for AI-assisted development
- Updating existing instruction files after project changes
- Standardizing AI agent behavior across team members
- Migrating from one AI tool to another

## Key Principle

**Do not duplicate specialized skills.** If a request falls into a specialized domain (e.g., Design System), delegate to the specialized skill when available.

**Use `AGENTS.md` as the shared project manual.** `AGENTS.md` is plain Markdown with no required fields. Cover the details an agent needs to work effectively: project overview, build and test commands, code style, testing expectations, security notes, PR/commit rules, and deployment gotchas.

**Handle `AGENTS.override.md` as a Codex-specific override, not the default.** Codex checks `AGENTS.override.md` before `AGENTS.md` at both global and project-directory scopes, and includes at most one instruction file per directory. If both files exist in the same directory, Codex uses `AGENTS.override.md` and ignores that directory's `AGENTS.md`. Create or update `AGENTS.override.md` only when the user explicitly wants a Codex-specific or nested-directory override.

**Respect Codex instruction discovery.** Codex builds its instruction chain once per run/session: global instructions first, then project files from repository root down to the current working directory. The global Codex directory defaults to `~/.codex` and can be changed with `CODEX_HOME`. Files closer to the current directory appear later and override earlier guidance. Codex skips empty files and stops adding files when the combined size reaches `project_doc_max_bytes` (32 KiB by default). If `~/.codex/config.toml` defines `project_doc_fallback_filenames`, Codex checks those names after `AGENTS.override.md` and `AGENTS.md`.

**Use `CLAUDE.md` only as Claude Code compatibility by default.** Claude Code reads `CLAUDE.md`, not `AGENTS.md` directly, so a shared setup needs a `CLAUDE.md` file that imports `AGENTS.md`.

## Quick Start

To generate a new AGENTS.md file:
1. Navigate to your project root
2. Tell the AI agent: "Use the agents-md-generator skill to create an AGENTS.md file"
3. Answer the interactive questions about your project
4. Review and customize the generated file

### Answering Questions (Convenient Formats)

When this skill asks numbered questions with lettered options, users can answer in any style:

- Short form (fast): `1a 2b 3c`
- Mixed form: `1a 2b 3c 4b (also scan packages/*) 5d`
- Full sentences: “Use medium scan depth and Docker Compose; service name is app.”

Short form is never required; it is only provided for convenience.

### Generation Modes

**Interactive Mode (Default):**
- Guides you through each phase with questions
- Best for first-time setup or complex projects
- Maximum customization

**Quick Mode:**
- Tell the AI: "Generate AGENTS.md in quick mode"
- Skips all questions, uses auto-detection only
- Best for experienced users or simple projects
- Uses Medium scan depth by default
- Generates all standard sections based on detection

## Interactive Workflow

### Phase 1: Initialization & Discovery

**Check for existing files:**
1. Look for `CLAUDE.md`, `AGENTS.md`, and `AGENTS.override.md` in the project root.
2. If `AGENTS.md` exists, ask user: "I found an existing AGENTS.md. Would you like to:"
   1. Update it (merge new content while preserving customizations)
   2. Replace it (generate fresh, backup existing)
   3. Cancel
   - Reply examples (optional): `1` or `update`; `2` or `replace`; `3` or `cancel`
3. If `CLAUDE.md` exists but `AGENTS.md` does not, ask user before changing it:
   1. Migrate to `AGENTS.md` as the primary file and replace `CLAUDE.md` with a compatibility reference to `AGENTS.md`
   2. Keep `CLAUDE.md` and `AGENTS.md` side by side with separate instructions for different AI agents
   3. Cancel
   - Reply examples (optional): `1` or `migrate`; `2` or `keep both`; `3` or `cancel`
4. If both `AGENTS.md` and `CLAUDE.md` exist, ask whether `AGENTS.md` should become the single source of truth with `CLAUDE.md` referencing it, or whether the user intentionally wants both files to remain independent.
5. If `AGENTS.override.md` exists, explain that Codex gives it priority over `AGENTS.md` in that directory. Ask whether to update the override, merge it back into `AGENTS.md`, or leave it as a Codex-specific override.

**Determine primary file:**
- Default: `AGENTS.md` as primary source of truth.
- `AGENTS.override.md` is not the primary file. Use it only for Codex-specific overrides, temporary overrides, or nested directory rules that should supersede broader `AGENTS.md` guidance for Codex.
- `CLAUDE.md` is a secondary compatibility file for Claude Code, because Claude Code reads `CLAUDE.md` rather than `AGENTS.md` directly. Do not use symbolic links; some AI agents may read both files and duplicate context.
- When sharing the same instructions with Claude Code, make `CLAUDE.md` a normal text file whose first line is:
  ```markdown
  @AGENTS.md
  ```
- Additional Claude-specific instructions may be added below the import only when the user explicitly wants them.
- If the project already has a meaningful `CLAUDE.md`, ask the user before replacing it. The user may prefer to keep both files with different guidance for different AI tools.

### Phase 1b: Agent Tooling & System Prompt Alignment (Scripted)

**Goal:** Detect AI tool instruction files, global system prompts, and MCP configs using scripts (not AI scanning) to save tokens and avoid missing overrides.

**Run the detection script (best effort):**
- bash/zsh: `bash skills/agents-md-generator/scripts/detect-agent-context --root .`
- Windows cmd: `skills\agents-md-generator\scripts\detect-agent-context.cmd --root .`

The script should report:
- Project instruction files for AI tools (Copilot, Cursor, Cline, Kilo Code, Roo Code, OpenCode, Codex, Claude Code)
- Global instruction files (e.g., `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.override.md`, `~/.codex/AGENTS.md`, `~/.codex/config.toml`, `~/.roo/rules/`, `~/.kilocode/rules/`)
- MCP config files and server names (from `.mcp.json`, `.roo/mcp.json`, `mcp_settings.json`, plus any `--mcp-path` entries)

**If script is unavailable:**
- Do a minimal manual check using the paths listed in `references/tech-stack-detection.md` under **AI Agent Tooling Detection**.

**Warn the user about overrides:**
- If `~/.claude/CLAUDE.md` or other global instruction files exist, explicitly warn that they can override project prompts.
- Ask the user to review or adjust those system prompts to avoid conflicts with this repo.

**Ask the user to confirm tool usage:**
```
I detected these AI tool instruction sources:
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .clinerules or .clinerules/ (Cline)
- .kilocoderules / .kilo/ / .kilocodemodes (Kilo Code)
- .roo/rules/ / .roo/rules-* / .roorules* (Roo Code)
- opencode.jsonc (OpenCode)
- AGENTS.override.md / AGENTS.md (Codex project instructions)
- ~/.codex/AGENTS.override.md / ~/.codex/AGENTS.md / ~/.codex/config.toml (Codex global instructions and config)
- .claude/CLAUDE.md or ~/.claude/CLAUDE.md (Claude Code)

Which of these do you actively use for this project, and should we align or ignore any of them?
```

**If MCP servers are detected:**
- Ask whether they should be used in this project.
- Capture a short purpose/usage note for each server.

### Phase 1c: Skill Library Duplicate Scan (Scripted)

If a `skills/` folder exists, run the duplicate scan script to avoid copy-pasted skills:
- bash/zsh: `bash skills/agents-md-generator/scripts/scan-skill-duplicates --skill