agents-md

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bootstrap AGENTS.md

Generate a project-tailored AGENTS.md, the canonical instruction file for AI coding agents working in a repository.

## What AGENTS.md Is

AGENTS.md is a root-level markdown file that tells any AI coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor, etc.) how to behave in this specific repo. It covers:

- **Safety invariants**: what agents must never do
- **Toolchain**: language runtimes, package managers, build tools
- **Architecture**: repo layout, key modules, data flow
- **Code discipline**: editing rules, file creation policy, backwards compat stance
- **Quality gates**: linters, tests, type checks agents must run
- **Session protocol**: how to land work cleanly so the next agent can pick up

## Process

### Phase 1: Discover the Repo

Run all discovery in parallel where possible. Gather:

1. **Root files**: `ls` the repo root. Look for README, package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, Dockerfile, docker-compose, .env.example, etc.
2. **Existing agent config**: Check for CLAUDE.md, .cursorrules, .cursor/rules/, .claude/settings.json, .github/copilot-instructions.md, CONTRIBUTING.md, .editorconfig
3. **Git info**: default branch name, recent commit style (`git log --oneline -20`), any branch naming conventions
4. **Tech stack detection**:
   - JS/TS: package.json → runtime (node/bun/deno), package manager (npm/yarn/pnpm/bun), framework
   - Python: pyproject.toml/setup.py/requirements.txt → manager (uv/pip/poetry), framework
   - Rust: Cargo.toml → edition, workspace layout
   - Go: go.mod → module path
   - Other: detect from file extensions and build files
5. **Directory structure**: Use Glob (`**/*`) and `ls` to map top-level and second-level directories (skip node_modules, .git, __pycache__, .venv, etc.)
6. **Testing setup**: test runner, test directory, how to run tests
7. **Linting/formatting**: eslint, prettier, ruff, black, clippy, golangci-lint, etc.
8. **CI/CD**: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, etc.
9. **Generated files**: any codegen, build outputs, compiled assets
10. **Issue tracking**: .beads/, Linear config, GitHub Issues conventions

**Check for existing AGENTS.md**: If one already exists, read it first. Ask the user whether to replace it entirely or merge discovered info into the existing structure. Preserve any custom rules or project-specific sections the user already wrote.

### Phase 2: Draft the AGENTS.md

Use the template below, adapting each section to what was discovered. **Omit sections that don't apply.** A Bash-only project doesn't need a "Generated Files" section if there aren't any.

**Key principles:**
- Be specific to THIS repo, not generic
- Include exact commands (not "run the linter" but `ruff check . --fix`)
- State the default branch by name
- List real directories from the repo layout
- Reference actual config files found

### Phase 3: Present and Refine

Show the draft to the user. Ask if anything should be added, removed, or adjusted. Common refinements:
- Adding project-specific forbidden patterns
- Adjusting the strictness of safety rules
- Adding tooling assumptions (what's installed on dev machines)
- Documenting deployment targets

Write the final AGENTS.md to the repo root.

## Template

Below is the canonical template. Adapt every section to the actual repo. Remove sections in `[brackets]` that don't apply. Replace all `{placeholders}`.

~~~markdown
# AGENTS.md: {Project Name}

> Guidelines for AI coding agents working in this codebase.

---

## Safety Rules

### Human Override

The user's instructions take precedence over everything in this file. If the user explicitly asks you to do something that contradicts a rule below, follow the user's instructions.

### No File Deletion

Never delete files or directories without explicit permission from the user in the current session. If something should be removed, ask first.

### No Destructive Git

The following commands are forbidden unless the user provides the exact command and explicit approval:

- `git reset --hard`
- `git clean -fd`
- `rm -rf`
- Any command that can delete or overwrite uncommitted work

Prefer safe alternatives: `git status`, `git diff`, `git stash`, copying to backups.

### No File Proliferation

Never create variant files (`main_v2.ts`, `component_backup.tsx`, `utils_improved.py`). Edit existing files in place. New files are only for genuinely new functionality.

---

## Toolchain

{Describe the exact runtimes, package managers, and build tools. Be prescriptive.}

[Example for JS/TS:]
- **Runtime:** Bun
- **Package manager:** Bun (`bun install`, `bun add`). Never use npm/yarn/pnpm.
- **Lockfile:** `bun.lock` only
- **Target:** Latest Node.js; no legacy compatibility needed

[Example for Python:]
- **Runtime:** Python 3.12+
- **Package manager:** uv (`uv pip install`, `uv sync`). Never use pip directly.
- **Lockfile:** `uv.lock`
- **Virtual env:** `.venv/` (managed by uv)

[Example for Rust:]
- **Edition:** 2024
- **Build:** `cargo build`, `cargo test`
- **Clippy:** All warnings are errors

From thunter009/skills, MIT.

More from thunter009/skills