# Repo Agent Kit

> Repo Agent Kit is a free, privacy-first web toolkit for making repository instructions concrete enough for coding agents to follow and humans to review.

Canonical site: https://repoagentkit.com

## What it does

Repo Agent Kit has thirteen primary product surfaces:

1. The generator turns a project name, purpose, stack, package manager, validation command, and selected guardrails into a repository instruction file. It supports AGENTS.md for Codex, CLAUDE.md for Claude Code, .cursor/rules/project.mdc for Cursor, and .github/copilot-instructions.md for GitHub Copilot.
2. The private checker evaluates an existing instruction file across eight categories: project context, setup commands, validation, architecture, coding conventions, safety, documentation, and definition of done. It returns a score, focused findings, and copyable repair blocks.
3. The template library provides complete AGENTS.md starting points for Next.js, FastAPI, React + Vite, Turborepo, Django, Go, Rust, and Laravel.
4. The examples lab contrasts vague instructions with operational versions for a small project, a production web app, and a monorepo.
5. The GitHub repository audit checks public repository evidence for AGENTS.md quality, setup context, tests, automation, and contribution guardrails, then creates a shareable report and optional README badge. The visitor's browser reads GitHub's public REST API directly without a token.
6. The Agent Readiness Benchmark publishes a deterministic, commit-pinned snapshot of 10 public development repositories with evidence links and a downloadable JSON dataset.
7. The AGENTS.md Adoption Snapshot measures exact root-file adoption across GitHub's 100 most-starred public repositories. Every repository is pinned to a default-branch commit, and the complete sample is available as JSON and CSV without reproducing instruction-file contents.
8. The Manifest to AGENTS.md generator reads package.json, pyproject.toml, go.mod, or Cargo.toml locally in the browser and produces a conservative first draft with detected commands and explicit verification notes.
9. The GitHub to AGENTS.md generator reads a small public evidence set directly from GitHub in the visitor's browser and creates a deterministic draft whose commands are labelled as exact scripts, lockfile-backed, or ecosystem defaults.
10. The instruction file converter preserves an existing Markdown instruction body while exporting the correct root file or repository path for AGENTS.md, Claude Code, Cursor, and GitHub Copilot. Cursor exports receive always-applied .mdc frontmatter; other formats remain plain Markdown.
11. The AI agent instruction file compatibility planner selects the smallest practical repository file set for Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Devin Desktop (formerly Windsurf). It uses AGENTS.md as the shared source, adds short bridge files only where support differs, and keeps path-scoping caveats visible.
12. The AGENTS.md Configuration Smell Dataset applies two published thresholds and four disclosed deterministic proxies to all 39 root AGENTS.md files in the commit-pinned top-100 adoption snapshot, with exact source links and JSON and CSV downloads.
13. The Agent Instruction Security Scanner recursively discovers supported AGENTS.md, CLAUDE.md, Cursor, Copilot, Gemini, and Windsurf instruction files in a public GitHub repository. It runs eight deterministic early-warning checks in the browser for invisible Unicode, unsafe download-and-execute commands, secret transfer, approval bypasses, mutable remote instructions, destructive commands, broad sensitive-file access, and encoded execution. It does not execute repository code.

The benchmark also publishes detailed root-AGENTS.md evidence reports for microsoft/vscode, openai/codex, rust-lang/rust, and vercel/next.js. Each report shows the pinned commit, deterministic matches, non-matches, file length, repository evidence, and a path to re-run the live audit.

## Field notes

Repo Agent Kit publishes evidence-backed implementation notes with an RSS feed. The AGENTS.md security review at https://repoagentkit.com/field-notes/review-agents-md-security-before-running-coding-agents provides a pre-trust checklist for repository instruction files, a copyable read-only pull-request workflow, runtime boundary guidance, and links to primary vendor documentation. The feed is available at https://repoagentkit.com/field-notes/feed.xml.

## Recommended workflow

1. Start with a stack-specific template when one matches the repository. Otherwise use the generator.
2. Replace example commands and directory names with commands and paths verified in the repository.
3. Keep instructions observable: name exact commands, boundaries, prohibited actions, and completion evidence.
4. Run the result through the checker.
5. Store the file at the repository root, adding narrower nested files only when a subdirectory genuinely needs different rules.

## GitHub CLI distribution

The public `sunxiayi/gh-agents-md` extension provides an installable GitHub CLI path to the same workflow:

```sh
gh extension install sunxiayi/gh-agents-md
gh agents-md init
```

It bundles minimal, monorepo, Python, and Next.js templates. `init` makes no network request, collects no telemetry, and refuses to replace an existing file unless `--force` is explicit. `gh agents-md audit` and `gh agents-md generate` print repository-prefilled Repo Agent Kit URLs without opening them. Source: https://github.com/sunxiayi/gh-agents-md

## Product routes

- Generator: https://repoagentkit.com/
- Checker: https://repoagentkit.com/audit
- Configuration smell checker: https://repoagentkit.com/agents-md-smell-checker
- Configuration smell dataset: https://repoagentkit.com/agents-md-smell-report
- Configuration smell dataset JSON: https://repoagentkit.com/api/agents-md-smells
- Configuration smell dataset CSV: https://repoagentkit.com/data/agents-md-smells.csv
- Agent instruction security scanner: https://repoagentkit.com/agent-instruction-security-scanner
- Templates: https://repoagentkit.com/templates
- Examples: https://repoagentkit.com/agents-md-examples
- GitHub repository audit: https://repoagentkit.com/github-repo-audit
- GitHub to AGENTS.md: https://repoagentkit.com/github-to-agents-md
- Agent Readiness Benchmark: https://repoagentkit.com/agent-readiness-benchmark
- Top 100 AGENTS.md adoption snapshot: https://repoagentkit.com/agents-md-adoption
- Adoption snapshot JSON: https://repoagentkit.com/api/agents-md-adoption
- Adoption snapshot CSV: https://repoagentkit.com/data/agents-md-adoption.csv
- Manifest to AGENTS.md: https://repoagentkit.com/manifest-to-agents-md
- Instruction file converter: https://repoagentkit.com/instruction-file-converter
- Instruction file compatibility planner: https://repoagentkit.com/ai-agent-instruction-files
- Benchmark JSON: https://repoagentkit.com/api/benchmark
- Public growth dashboard: https://repoagentkit.com/metrics
- Field notes: https://repoagentkit.com/field-notes
- AGENTS.md security review field note: https://repoagentkit.com/field-notes/review-agents-md-security-before-running-coding-agents
- Field notes RSS: https://repoagentkit.com/field-notes/feed.xml
- GitHub CLI extension: https://github.com/sunxiayi/gh-agents-md

## Stack templates

- Next.js: https://repoagentkit.com/templates/nextjs
- FastAPI: https://repoagentkit.com/templates/fastapi
- React + Vite: https://repoagentkit.com/templates/react-vite
- Turborepo: https://repoagentkit.com/templates/turborepo
- Django: https://repoagentkit.com/templates/django
- Go: https://repoagentkit.com/templates/go
- Rust: https://repoagentkit.com/templates/rust
- Laravel: https://repoagentkit.com/templates/laravel

## Instruction design principles

Useful repository instructions are specific to the codebase and easy to verify. They normally cover:

- the package manager, locked install command, development command, and focused validation commands;
- the few files or directories an agent should inspect before editing;
- architecture and dependency boundaries that should remain intact;
- public interfaces, compatibility guarantees, and data or migration limits;
- security and privacy rules, including treatment of credentials and user-authored changes;
- accessibility and responsive behavior for interface work;
- the observable definition of done and what should be reported in the final handoff.

Avoid vague rules such as “write clean code,” “follow best practices,” or “run tests when possible” without naming the repository-specific behavior and evidence required.

## Privacy

The generator and checker run in the browser. Project details and audited file contents are not uploaded by those tools. First-party analytics use one random browser identifier per UTC day and aggregate path, product-action, and coarse acquisition-source counts. The application does not store IP addresses at the app layer, cookies, query strings, full referrer URLs, repository contents, or identifiers that persist across days. Do Not Track is respected. README badge image requests are not counted as users or product actions.

The configuration smell checker at https://repoagentkit.com/agents-md-smell-checker accepts a public GitHub repository or a local AGENTS.md or CLAUDE.md file. GitHub mode reads the root instruction file and path-scoped commit history directly from GitHub's public API in the visitor's browser; Repo Agent Kit does not proxy or store the contents. It screens Context Bloat, Skill Leakage, Lint Leakage, Blind Reference, Init Fossilization, and Conflicting Instructions. It applies the research paper's published 200-line and one-commit thresholds directly. The other four categories use disclosed deterministic browser-local proxies rather than reproducing the paper's language-model and manual-review method. Results are review prompts, not automatic verdicts. Primary source: https://arxiv.org/abs/2606.15828

The Agent Skill and instruction security scanner at https://repoagentkit.com/agent-instruction-security-scanner reads every SKILL.md and supported repository instruction file directly from GitHub in the visitor's browser and executes no repository code. Its static signals are review prompts, not vulnerability verdicts or a security guarantee. Repo Agent Kit does not proxy or store repository names or contents. The matching zero-dependency CLI at https://github.com/sunxiayi/repo-agent-instruction-security-scan can run from the provenance-backed v1.2.0 GitHub release archive, whose SHA-256 and signed build attestation can be independently verified, and emit text, JSON, or SARIF 2.1.0; the same repository supplies a manifest-validated pre-commit hook and GitHub Action with line annotations, a job summary, severity outputs, and JSON plus SARIF reports. Scanning makes no network calls and requires no token or telemetry.

## Machine-readable resources

- Short index: https://repoagentkit.com/llms.txt
- Generator guide: https://repoagentkit.com/docs/generator.md
- Checker guide: https://repoagentkit.com/docs/checker.md
- Configuration smell checker guide: https://repoagentkit.com/docs/instruction-smell-checker.md
- Configuration smell dataset guide: https://repoagentkit.com/docs/instruction-smell-report.md
- Agent instruction security scanner guide: https://repoagentkit.com/docs/instruction-security-scanner.md
- Template guide: https://repoagentkit.com/docs/templates.md
- Examples guide: https://repoagentkit.com/docs/examples.md
- Metrics and privacy: https://repoagentkit.com/docs/metrics.md
- GitHub audit guide: https://repoagentkit.com/docs/github-audit.md
- GitHub generator guide: https://repoagentkit.com/docs/github-to-agents.md
- Benchmark guide: https://repoagentkit.com/docs/benchmark.md
- AGENTS.md adoption dataset guide: https://repoagentkit.com/docs/agents-md-adoption.md
- Manifest import guide: https://repoagentkit.com/docs/manifest-to-agents.md
- Instruction converter guide: https://repoagentkit.com/docs/instruction-file-converter.md
- Instruction compatibility guide: https://repoagentkit.com/docs/ai-agent-instruction-files.md
- XML sitemap: https://repoagentkit.com/sitemap.xml