Introduction

Buddy Agent Harness gives a repository one canonical agent configuration (a root AGENTS.md and an .agents/ tree) and bridges the agent harnesses that cannot read it directly.

Use it when a team works with more than one agent and does not want to maintain equivalent instructions in CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md, and a per-harness skills directory at the same time.

The model

The repository root is the consumer boundary. Everything portable lives there:

repository/
├── AGENTS.md                 # project-level agent instructions
└── .agents/
    ├── AGENTS.md             # shared repository guidance
    ├── skills/
    │   └── <skill>/SKILL.md  # reusable capabilities
    └── <tool-setting>        # separately named tool configuration

Harness-specific files are projections of that source, never a second source of truth. Most harnesses need no projection at all: Codex, Cursor, GitHub Copilot CLI, Gemini CLI, and Devin Desktop read .agents/skills/ natively. Only Claude Code reads solely its own directory and needs a link.

This is a consolidation job, not a copy-everywhere job. See Configuration Layout for the full layout and Harness Differences for who needs what.

What it will not do

Buddy Agent Harness does not invent instructions or rewrite a team’s policy. It preserves user-authored configuration and projects an artifact only where a documented, safe mapping exists. A setting with no such mapping (MCP servers, subagents, hooks, path-scoped rules) stays canonical rather than being guessed at or converted.

It also stays out of everything that is not local agent configuration: no changes to CI, workflows, repository settings, security scanning, or branch rules.

Install

In Claude Code, install the plugin and its init skill from the cyberplace marketplace:

/plugin marketplace add cyberuni/cyberplace
/plugin install buddy-agent-harness@cyberplace

Install from the marketplace rather than from a git checkout. The init and doctor skills run the CLI that ships with the plugin, and that CLI has dependencies, which an npm-backed install brings with it and a git source does not. A git-sourced install still works: both fall back to fetching the pinned version with npx. See Skill Scripts for the pattern and why the fallback stays.

Initialize a repository

From the repository root, invoke the init skill:

/buddy-agent-harness:init

Any agent that reads .agents/skills/ can be asked in prose instead:

Initialize this repository's agent configuration.

The skill surveys what configuration you already have, proposes a consolidation plan, applies it once you approve, and runs the CLI to create the projections. That is the primary path. Start at Skill: init.

The CLI alone handles only the linking step. On a repository that is already consolidated you can run it in a shell by mounting the package on repobuddy. See the CLI reference.

Check the bridges

A link that a clone failed to create is silent: the harness finds no directory and loads zero project skills. Nothing here repairs anything; both halves only report.

Ask the doctor skill, which runs the command and reads the report back to you:

/buddy-agent-harness:doctor

Or run the command yourself, on any clone, with the plugin installed or not:

npx -y buddy-agent-harness doctor --format text

The command prints TOON by default, which is compact for an agent to parse. --format text prints an aligned report for a person.

Start small

You do not need to create every configuration artifact before initializing. Start with one repository skill in .agents/skills/<name>/SKILL.md and a root AGENTS.md. Re-running initialization is idempotent: an existing symlink that already resolves into .agents/ is left alone.