Glossary

Each entry gives the short definition and links to the page that owns the topic. Where a term is used inconsistently in the wider ecosystem, the definition here is the one this documentation means.

Configuration

canonical configuration: the repository-local .agents/ tree and root AGENTS.md. It belongs to the repository rather than to any one harness. See Configuration Layout.

canonical instructions: AGENTS.md and .agents/AGENTS.md, holding repository and shared behavioral guidance. Initialization does not rewrite them.

canonical skills directory: .agents/skills/, the capabilities portion of the canonical configuration. Note that this path is a convention, not part of the Agent Skills specification. See Open Standards.

canonical skill: an immediate directory under .agents/skills/. Files at that level are ignored.

tool setting: harness or tool configuration kept in its own separately named file under .agents/, because each setting has its own schema and compatibility rules.

golden set: the user-authored canonical list of MCP servers at .agents/buddy-agent-harness/mcp.toml, one entry per server in the superset of fields the supported hosts accept. See MCP Servers.

governance: a version-pinned Markdown rule set that a skill loads, such as skill-design or agent-tool-output. A governance is one use of a reference. See reference.

reference: a Markdown document an agent reads on demand, fetched by name rather than loaded at session start. It resolves through the managed, project, user, and plugin tiers, and the higher layer decides how it combines with the ones below. See References and Skills.

agent worktree: a git worktree Claude Code creates for a --worktree session or an isolated subagent, under .claude/worktrees/<name>/. See Agent Worktrees.

last-projected record: .agents/buddy-agent-harness/mcp.projected.json, the per-target record of what was last written from the golden set, and the drift baseline for a file git cannot speak for. See MCP Servers.

Harnesses

harness: a coding-agent runtime with its own skill discovery location. Claude Code, Codex, and Cursor are harnesses.

active harness: the harness in which initialization is invoked.

enabled harness: the active harness plus any harness the user explicitly chose. The enabled set is derived on every run and only ever grows. See Configuration Layout.

native harness: a harness that reads .agents/skills/ directly at project scope, so the canonical directory is its directory and nothing is written for it. See Harness Differences.

polyfill: the umbrella for whatever makes canonical configuration reach a harness that cannot read it, covering both a projection and a bridge. As with a browser polyfill, nothing is written for a harness that already reads the canonical format. The homepage uses this word; the rest of the documentation names the specific mechanism.

projection: a directory-level symlink from a harness path to .agents/skills, such as .claude/skills → ../.agents/skills. Only Claude Code needs one. Where symlinks are unavailable the initializer copies instead, which is a snapshot rather than a live projection.

bridge: the harness-specific edit that lets a harness reach AGENTS.md when it cannot read that file directly. One is left: the Gemini CLI context.fileName setting. The CLI does not write it, because it needs judgment about user-authored content. The init-buddy-agent-harness skill handles it.

shadow: a file that suppresses an AGENTS.md a harness would otherwise read, because the harness prefers its own filename where both are present. A CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md beside an AGENTS.md is the case, and Claude Code covers it. The opposite of a bridge: nothing has to be written for the harness to read AGENTS.md, and something has to be dealt with before it can.

skill bridge: whatever points a harness at .agents/skills, whether a symlink or a copy. This is the sense the doctor command prints, where each row of its bridges list is one harness path it checked. A working skill bridge is a projection; the word covers the broken states too, which is why the diagnostic uses it. See doctor.

enabled vs. projected: enabling a harness states what the repository supports; projecting writes a link. For a native harness the two differ, so the CLI result separates native from linked. See Harness Differences.

Skills

skill: a SKILL.md file, holding frontmatter that governs when it loads and a body the agent follows once loaded. Commands, gateways, and personas are all skills. See Kinds of Skill.

launcher: a self-contained bundle a skill ships in its own scripts/ directory, built at package time from the project’s source with every runtime dependency inlined. It lets an installed skill run its command without fetching anything or depending on a node_modules above it. Shipped through the package’s own distribution channel rather than committed; a git-sourced install carries no bundle and falls back to a pinned npx invocation. See Skill Scripts.

selection, visibility, effect: the three independent axes that distinguish kinds of skill, namely how it is chosen, who may choose it, and what running it changes. The familiar names are recognizable combinations of values on these axes, not a fixed list.

command: a skill selected explicitly by the user, performing an action. See Commands.

gateway skill: a skill whose effect is routing rather than action. It directs the request to the right place. See Gateway Skill.

persona skill: a skill selected explicitly by the user whose effect is a stance rather than an action. See Persona.

direct invocation skill: an agent-only skill selected by name, with a description kept deliberately unmatchable so it is never auto-loaded. See Direct Invocation Skill.

discipline: a skill triggered by an event, whose effect is a stance.

Instructions

purpose: what a block of instruction is for, whether procedure, criteria, policy, reference, menu, tone, or structure. A property of the prose, not of the file. See Instruction Purpose.

target: which of the agent’s outputs an instruction governs, and therefore who eventually reads it. Separating targets is what lets contradictory instructions coexist. See Instruction Target.

file type matching, description matching, prose matching: the three mechanisms that specify a target, acting at different moments. A path glob is evaluated by the harness, a description is judged by the agent at load time, and a distinction is drawn in the body while working. See Instruction Target.