A reference template for portable, vendor-agnostic agent environments.
If you’ve ever tried to roll out “AI coding agents” to a team, you’ve probably felt the trap:
- Every vendor wants its own config format
- Rules, skills, tools (MCP), and hooks get duplicated across files
- One small change turns into five PRs and a lot of drift
This repo is a pragmatic escape hatch: a collection of patterns that lets you define your agent environment once, keep it reproducible, and run it across multiple agent runtimes (Copilot, Claude Code, Gemini CLI, etc.) without betting the farm on any single provider.
Jump to: Quick Start · 5 Patterns · Tools · Agents · Skills · Docs
- Portability (no lock-in): Define skills, rules, MCP configs, commands, subagents, and hooks once, then run them anywhere.
- Instant cloud agents: Fast startup via dynamic prebuilds (Copilot runner images / Codespaces).
- Fast onboarding: A bootstrapped dev environment that “just shows up” for new contributors.
- Incremental adoption: Adopt one pattern at a time. Keep what helps; delete what doesn’t.
These patterns are the heart of the template. Everything else is implementation detail.
Instead of maintaining a pile of CLAUDE.md / GEMINI.md / tool-specific config files, keep a single source of truth and generate outputs.
- Source of truth: .rulesync and rulesync.jsonc
- Generator: rulesync
- Result: tool-specific outputs (for example .claude/, .gemini/, .opencode/) are generated and gitignored
This makes the project advocate for open, vendor-agnostic standards (for example AGENTS.md) rather than a growing pile of proprietary equivalents.
Skills are powerful, but “pull from main” is a supply-chain footgun.
- Skill sources are declared in rulesync.jsonc
- Resolved versions are pinned via rulesync.lock
- Default behavior is deterministic (
--frozen) so local dev and CI match
Tool access is part of the environment, not an afterthought.
- MCP servers are defined once in .rulesync/mcp.json
- rulesync distributes them to each supported agent format
Onboarding succeeds when “works on my machine” stops being a thing.
- Toolchain is defined in devenv.nix + devenv.yaml (pinned via devenv.lock)
- direnv can auto-load the environment on
cdvia .envrc
5) Prebuilt cloud agents (devenv-actions)
Waiting for environment bootstrapping on every run is the quiet productivity killer.
- GitHub Actions can prebuild runner snapshots for faster Copilot setup
- There’s also a dynamic fallback path if the snapshot isn’t present
See Copilot fast path.
Click the badge at the top of this README. It opens a fully bootstrapped environment.
Prereqs:
Then:
git clone https://github.com/LN-Zap/agent-playground.git
cd agent-playground
npm installnpm install does more than install Node dependencies in this repo: a postinstall hook in package.json runs npx rulesync install --frozen (using the pinned versions in rulesync.lock) and then regenerates the agent-specific outputs with npx rulesync generate --delete.
Optional (recommended):
direnv allowThe goal is to make changes once, then let automation do the boring part.
- Rules, MCP, subagents metadata: .rulesync/
- Targets, features, skill sources: rulesync.jsonc
- Environment / toolchain: devenv.nix + devenv.yaml
For the detailed mechanics, see Synchronization model.
- Regenerate all agent outputs (deterministic):
npx rulesync generate --delete - Intentionally refresh pinned sources (updates rulesync.lock):
npm run rulesync:update
These MCP tools are example defaults enabled in this template. You can update, replace, or extend them with any other MCP servers that fit your workflow.
| Name | Description |
|---|---|
| context7 | Documentation and reference retrieval via Context7 MCP. |
| github | GitHub MCP integration for repository, issue, and PR operations. |
| playwright | Browser automation and testing through Playwright MCP. |
| chrome-devtools | Chrome DevTools MCP for browser inspection and debugging. |
| deepwiki | DeepWiki MCP for AI-powered repository documentation queries. |
To add support for additional MCP tools, update the mcpServers object in .rulesync/mcp.json.
These agent targets are example defaults enabled in this template. You can add, remove, or swap targets based on your preferred tools and delivery model.
| Name | Description |
|---|---|
| Copilot | AI coding assistant integrated across GitHub and major IDEs. |
| Claude | Anthropic's CLI-first coding agent for local development workflows. |
| Codex | AI model and ecosystem support for code generation and reasoning. |
| Gemini | Google's open-source command-line AI agent for coding and automation. |
| OpenCode | Open-source AI coding agent with support for flexible model providers. |
| Generic | Broad compatibility with agents supporting open instruction standards. |
To add support for additional agents, configure the targets array in rulesync.jsonc.
These skills are example defaults bundled in this template. You can replace these with any public or private skill sources that better match your domain.
| Name | Description |
|---|---|
| skill-creator | Guidance for creating and refining reusable skills. |
| rulesync | Unified cross-agent rules and skills synchronization tooling. |
Skill bundles are configured in the sources section of rulesync.jsonc.
Some setups may need GitHub auth for fetching skills.
GITHUB_TOKEN: recommended for local development when using GitHub-hosted sources (see .env.example)
Contributions focusing on new provider-agnostic patterns and cross-agent workflows are welcome!