Skip to content

SKILL.md

Latest commit

 

History

History
81 lines (65 loc) · 3.56 KB

SKILL.md

File metadata and controls

81 lines (65 loc) · 3.56 KB
Raw
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 version
agent-next
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

  1. Analyze the project — read package.json/pyproject.toml, understand language/framework/structure
  2. Check what's missing — call check_repo_readiness MCP tool or run npx agent-ready check .
  3. Read the relevant reference — for each missing area, read the reference doc below
  4. Generate project-specific configs — use your understanding of THIS project, not generic templates
  5. 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/CODEOWNERS
  • CONTRIBUTING.md, SECURITY.md, LICENSE
  • .gitignore, .gitattributes

DevContainer

  • .devcontainer/devcontainer.json

Security

  • .github/dependabot.yml — grouped updates
  • Push protection enabled
  • CodeQL default setup enabled