| name | agent-ready |
| description | Best practices for setting up high-quality GitHub repos for AI coding agents. Use when setting up a new repo, improving an existing repo's infrastructure, or answering "what does this repo need for agents to work effectively". Triggers on "set up repo", "make repo agent-ready", "repo best practices", "/agent-ready". |
| license | MIT |
| metadata | {"author":"agent-next","version":"0.2.0"} |
Agent-Ready: Repo Setup Best Practices
A curated collection of best practices for standard high-quality GitHub repos and AI coding agent workflows. Read this to learn what to set up — then use your own intelligence to generate project-specific configs.
Workflow
- Analyze the project — read package.json/pyproject.toml, understand language/framework/structure
- Check what's missing — call
check_repo_readiness MCP tool or run npx agent-ready check .
- Read the relevant reference — for each missing area, read the reference doc below
- Generate project-specific configs — use your understanding of THIS project, not generic templates
- Verify — run linters, tests, check CI workflows are valid
The 9 Areas
| Area | Reference | What It Covers |
|---|
| Agent Guidance | references/agent-guidance.md | AGENTS.md, CLAUDE.md, copilot-instructions, cursor rules |
| Code Quality | references/code-quality.md | Linters, formatters, type checkers, .editorconfig |
| Testing | references/testing/ | BDT methodology, test scaffolds, coverage (6 detailed refs) |
| CI/CD | references/ci-cd.md | GitHub Actions: ci.yml, claude.yml, copilot-setup-steps.yml |
| Hooks | references/hooks.md | Git pre-commit (Lefthook/Husky) + Claude PostToolUse hooks |
| Branch Rulesets | references/branch-rulesets.md | GitHub rulesets via API (require PR, reviews, status checks) |
| Repo Templates | references/repo-templates.md | Issue forms, PR template, CODEOWNERS, CONTRIBUTING, SECURITY |
| DevContainer | references/devcontainer.md | .devcontainer for reproducible agent environments |
| Security | references/security.md | Dependabot, push protection, CodeQL, secret scanning |
Quick Reference: Files a Repo Should Have
Agent guidance (all tools)
AGENTS.md — cross-tool standard (Claude, Copilot, Cursor, Gemini)CLAUDE.md — Claude Code specific (can import AGENTS.md via @AGENTS.md).github/copilot-instructions.md — GitHub Copilot.github/workflows/copilot-setup-steps.yml — Copilot coding agent environment.cursor/rules/*.mdc — Cursor IDE
Code quality
- Linter + formatter config (biome.json or ruff in pyproject.toml)
- Type checker config (tsconfig.json strict or mypy)
.editorconfig
Testing
- Test directory structure (tests/unit/, tests/integration/, tests/e2e/)
- Test runner config
- Coverage config with thresholds
CI/CD
.github/workflows/ci.yml — lint, typecheck, test, build.github/workflows/claude.yml — Claude Code Action for PR review
Hooks
- Pre-commit: lefthook.yml or .husky/
- Claude:
.claude/settings.json with PostToolUse hooks
Branch rulesets
- Require PR before merge
- Require reviews + status checks
- Prevent force push and branch deletion
Repo templates
.github/ISSUE_TEMPLATE/*.yml — YAML forms (not Markdown).github/PULL_REQUEST_TEMPLATE.md.github/CODEOWNERSCONTRIBUTING.md, SECURITY.md, LICENSE.gitignore, .gitattributes
DevContainer
.devcontainer/devcontainer.json
Security
.github/dependabot.yml — grouped updates- Push protection enabled
- CodeQL default setup enabled
