Opinionated GitHub template for teams who want reproducible, multi-agent software delivery with shared instructions, quality gates, and low-context-rot workflows.
Best for: maintainers who use Claude Code, Gemini CLI, OpenCode, Qwen Code, Jules, Windsurf, Cursor, Copilot Chat, or mixed agent stacks in the same repository.
This template gives you:
- One canonical instruction source via
AGENTS.md - Reusable, versioned skills in
.agents/skills/ - Tool-specific compatibility layers — not duplicated agent logic
- Commit-time and CI-time quality enforcement
- Patterns for sub-agents, task delegation, and context isolation
Quick Links: Quick Start · Why this template · Agent compatibility · Architecture · Adoption paths · Documentation
Most AI coding setups break down in one of three ways:
- Instructions drift across tool-specific files and diverge over time
- Quality checks happen too late (post-PR, or not at all)
- Long agent sessions accumulate noisy context and produce inconsistent changes
This template addresses each problem with an opinionated default:
- ✓ Multi-Agent Support: Works with 7+ AI coding tools simultaneously
- ✓ Skills System: Reusable knowledge modules in canonical location
- ✓ Quality Gates: Automatic lint, test, format before commits
- ✓ CI State Artifacts:
.github/ci-status/ci-status.jsonand.github/ci-status/ci-summary.mdtrack CI health for agents - ✓ Context Discipline: Prevents context rot with sub-agents and hooks
- ✓ Dependabot Integration: Automated security and version updates
| Problem | Typical setup | This template |
|---|---|---|
| Shared agent instructions | Duplicated .md files per tool |
AGENTS.md → canonical source, thin tool overrides |
| Reusable domain knowledge | Prompt snippets copied between chats | Versioned skills in .agents/skills/ |
| Tool compatibility | Separate hand-maintained config per agent | Symlinks + override files per tool |
| Quality enforcement | Manual or post-PR only | Pre-commit hook + CI quality gate |
| Long-session context drift | Monolithic prompts | Sub-agent and delegation patterns |
Use this template when you want a repository structure that survives:
- Model version changes
- Adding a second or third AI tool to your workflow
- Team growth beyond a single maintainer
| Tool | Root config | Skills source | Integration style |
|---|---|---|---|
| Claude Code | CLAUDE.md |
.claude/skills/ → individual symlinks to .agents/skills/ |
Override file + per-skill symlinks |
| Qwen Code | QWEN.md |
.qwen/skills/ → individual symlinks to .agents/skills/ |
Override file + per-skill symlinks |
| Gemini CLI | GEMINI.md + .gemini/config.yaml |
.agents/skills/ (direct read) |
Override file + direct canonical path |
| OpenCode | opencode.json |
.agents/skills/ (direct read) |
JSON config + direct canonical path |
| Windsurf | .windsurf/ |
.windsurf/skills → directory symlink to .agents/skills/ |
Directory config + directory symlink |
| CommandCode | .commandcode/ |
.agents/skills/ (direct read) |
Directory config + taste learning |
| Cursor | .cursorrules |
.cursor/rules.md |
Override file + rules adapter |
| Copilot Chat | AGENTS.md |
Via repo docs | Best-effort structured compatibility |
All tools share the same canonical instruction source (AGENTS.md) and canonical skills
directory (.agents/skills/). Tool-specific files contain only true overrides — never
duplicated instructions.
flowchart TD
A["AGENTS.md<br/>canonical instructions"] --> B["Tool overrides<br/>CLAUDE.md / GEMINI.md<br/>QWEN.md"]
A --> C[".agents/skills/<br/>canonical skills"]
C --> D[".claude/skills<br/>per-skill symlinks"]
C --> E[".qwen/skills<br/>per-skill symlinks"]
C --> F[".windsurf/skills<br/>directory symlink"]
C --> G["Gemini / OpenCode / Jules / CommandCode<br/>direct reads"]
B --> H[".cursorrules<br/>Cursor adapter"]
A --> I["Scripts & hooks"]
I --> J["pre-commit quality gate<br/>scripts/quality_gate.sh"]
I --> K["CI workflows<br/>.github/workflows/"]
K --> L[".github/ci-status/<br/>state artifacts"]
Rule:
AGENTS.mdis the only place shared instructions live. Tool files extend or override; they never duplicate.
| Starting point | Recommended first step |
|---|---|
| New repository | Use this template directly — all structure is in place |
| Existing repo, one AI tool | Add AGENTS.md first, then migrate reusable prompts into .agents/skills/ |
| Existing repo, multiple agent files | Consolidate shared instructions into AGENTS.md; keep only true tool-specific overrides |
| Existing repo, flaky automation | Start with quality_gate.sh + CI status artifacts before expanding agent workflows |
See agents-docs/MIGRATION.md for step-by-step migration guides.
# AGENTS.md
## Development Phases
We use a GOAP approach combined with ADRs and TRIZ for structured development.
## Quality Gate (Required Before Commit)
Use the `static-analysis` skill to triage and fix any findings before committing.
## Code Style
- Max 500 lines/file; 250/SKILL.md; 200/AGENTS.md
- No hardcoded values: use relative paths, runtime derivation, env vars.agents/skills/goap-agent/
└── SKILL.md ← instructions for breaking complex tasks into atomic goals
SKILL.md contains focused, reusable instructions for one domain.
Agents load individual skills on demand rather than injecting everything at once.
{
"status": "passing",
"last_run": "2026-06-05T16:47:55Z",
"failing_jobs": [],
"workflow_url": "https://github.com/.../actions/runs/27027831423"
}Agents read this artifact to understand the current CI state before proposing changes, avoiding suggestions that fix one check while breaking another.
# Evaluating this template itself:
git clone https://github.com/d-o-hub/github-template-ai-agents.git
cd github-template-ai-agents
# After creating YOUR repo from the template, clone that instead.
./scripts/bootstrap.shSee QUICKSTART.md for prerequisites, troubleshooting, and per-tool
verification steps. If bootstrap fails, run ./scripts/doctor.sh for diagnostics.
All agents read from AGENTS.md — CLI-specific files (CLAUDE.md, GEMINI.md,
QWEN.md, .cursorrules) contain only overrides.
AGENTS.md → Single source of truth
├── CLAUDE.md → Overrides only (@AGENTS.md)
├── GEMINI.md → Overrides only (@AGENTS.md)
├── QWEN.md → Overrides only (@AGENTS.md)
├── .cursorrules → Cursor adapter
└── opencode.json → Configuration
Skills live canonically in .agents/skills/. Claude Code and Qwen Code use per-skill
symlinks; Windsurf uses a directory symlink; Gemini CLI, OpenCode, and Jules read
directly from .agents/skills/:
.agents/skills/ # Canonical source (single location)
├── goap-agent/
├── shell-script-quality/
└── readme-best-practices/
.claude/skills/ # Per-skill symlinks → ../../.agents/skills/<skill>
.qwen/skills/ # Per-skill symlinks → ../../.agents/skills/<skill>
.windsurf/skills # Directory symlink → ../.agents/skills
Delegate isolated tasks to sub-agents for context isolation:
graph LR
A[Main Agent] --> B[Sub-Agent 1]
A --> C[Sub-Agent 2]
B --> D[Task Complete]
C --> E[Task Complete]
D --> F[Synthesize]
E --> F
- AGENTS.md — main agent instructions (single source of truth)
- EVALS.md — (Template) Agent quality and performance tracking
- USE_RESTRICTIONS.md — (Template) Agent usage policies
- Quick Start — setup, troubleshooting, per-tool verification
- Harness Overview — architecture and patterns
- Skills Guide — creating reusable skills
- Sub-Agents — context isolation patterns
- Hooks — pre/post tool hooks
- Context — back-pressure mechanisms
- Migration — adopting in existing projects
- Adoption profiles — minimal CI, skill packs, light process
- Available Skills — agents skills overview
- Monorepo Example — Bun + Turbo project structure
We welcome contributions! See our Contributing Guide for:
- Development environment setup
- Good first issues
- Code style and testing requirements
- Pull request process
- Issue Tracker — report bugs
- Discussions — ask questions
This project is licensed under the MIT License — see the LICENSE file for details.
Built with AI agents. Maintained by humans.