Giving your coding agent the instructions, over MCP or as skills

What question it answers

"How do I get my agent to actually use this?" — and, more usefully, "what does my harness have to support before it can?"

The failure the packaging discipline prevents is specific. A skill that says "read ARCHITECTURE.md and the domain guide first" behaves in exactly two ways: inside this repository it works, and installed into a stranger's project it loads, announces itself, finds no such files, and then produces confident instructions about a codebase it never read. The user sees a skill that triggered and answered — not one that failed — which is strictly worse than shipping nothing.

What it does

The portability fix is to reach the project through a command rather than a path. Every shipped skill opens with the same byte-identical orientation block: run the application inspection, read `valid`, then `problems[]`, then `limitations[]`, and treat every limitation as a hard boundary on what may be claimed. The block is identical in all of them on purpose — an agent should not have to learn a new preamble per skill.

Skills declare what they need in frontmatter: a `tier` (`any-project`, `generated-project`, `repository`), the one `command` that makes them portable, the `projectSurface` source paths they need, the `repositorySurface` documents that ship only here, and `degradesTo` — one sentence saying what the skill falls back to when the repository surface is missing. A skill that cannot state its own degraded mode has not thought about being installed. Twelve skills exist under `.claude/skills/`, mirrored byte-for-byte under `.agents/skills/`, with eleven published in the distributable `skills/` subset; the one held back is the repository-tier review skill, which reviews pull requests against documents that ship nowhere else.

Two MCP servers ship over newline-delimited JSON-RPC on stdio, with diagnostics on stderr only because stdout is reserved for the protocol. The application server exposes nine tools (`crm_project_context`, `crm_list_opportunities`, `crm_create_opportunity`, `crm_request_stage_change`, `crm_list_approvals`, `crm_decide_approval`, `crm_get_trace`, `crm_scaffold_module`, `crm_doctor`), five resources and two prompts. A second documentation server exposes `search_docs`, `get_capability` and `check_job` over the documentation index, the claims ledger and the jobs index. Code-generating and destructive tools are dry-run unless `apply` is explicitly true — `crm_scaffold_module` declares `apply` with a default of `false`, and the server's own instructions state the rule to the client.

What a harness must provide is four things: run a shell command and read stdout, read the exit code, parse JSON, and read and write files in the repository. That is the whole list — Node 22+ and a checkout. What it does not need is an MCP server, a network, credentials, a database, a long-lived process or any agent-specific format.

Because output determinism is asserted rather than promised, a harness can cache a report, diff two of them or commit one, and a difference always means the project changed. No absolute path appears in either machine-readable report — not the repository root, not a temporary directory, not the invoking user's home.

What it refuses to claim

The skills and MCP surfaces are the third place in this cluster where the honest answer is that there are no limitation codes, and the packaging guide is unusually direct about why each gap is a gap rather than a rough edge.

`requires` is a declaration, not an enforced check. Nothing parses it today; it is honest metadata a future gate or a human reading a diff can act on, and a skill can declare `tier: any-project` and still name a path — only review catches that. The distribution check still classifies ten of eleven skills as repository-bound because its pattern matches document paths anywhere in a skill body and cannot tell a prerequisite from background reading, so that note is accurate about the text and pessimistic about the behaviour.

Gemini gets nothing, on purpose. Two harnesses have skill files, and a file written for a third by guessing at its conventions — file name, location, front-matter, discovery rules — would look supported and silently never load, which is worse than none. The two supported copies are byte-identical and a checker enforces it, and that is also the honest description of the architecture: there is no canonical semantic source with generated adapters, there are two copies kept in step by a checker. Building the canonical source and a deterministic sync is roadmap work (DX2).

The tier-2 audience now has a producer, and it is not published. the project bootstrap emits a customer's own repository from a checkout — proven by tests/project-bootstrap.test.js — while the npm name it would ship under is still an empty reservation.

And portability is not authorization. None of this adds authentication, tenancy or roles, and a skill running in a stranger's project runs with that user's full authority — the inspection it performs imports the project's composition, which executes it. Isolation, not a sandbox. The MCP surface inherits the same boundary: mutation over MCP is scoped narrowly and never bypasses services or workflows, and remote mutation stays gated behind production work that has not been done.

What it costs to run

Nothing recurring. Both agent-facing commands start, answer and exit; there is no daemon to keep alive and no state to maintain between calls. The MCP servers are stdio processes your harness starts and stops.

Exit codes are identical across the two agent surfaces — `0` valid, `1` problems with the complete report still printed, `2` could not be read at all — so a harness that branches only on zero versus non-zero still behaves correctly.

The surface an agent must learn is budgeted and the budget is enforced. `node scripts/surface-check.js` printed here: 1/1 goal entry points, 12/12 skills, 9/10 always-on tools, 11/11 distinct commands across the skills. Every ceiling carries a written reason — a dozen skills is where descriptions start competing rather than dividing, and around ten always-on tools is where a namespace starts consuming context before any work begins. The check fails the build when the surface exceeds it, so raising a ceiling is a deliberate edit with an argument attached rather than a quiet drift.

Where it fits

It is the layer between the seven commands and whatever is driving them. The whole point of the harness contract is that the value lives in the CLI and its JSON contracts, not in any harness-specific integration — a harness adapter may change where a file lives and how it is announced, and must never change what the instructions say, or two harnesses stop being the same product.

The honest neighbours are two "not supported" rows that bound the whole surface. There is no registry, publication, remote install, auto-update, signing or hot loading — packages and skills are checked-in source. And there is no team or tenant permission enforcement anywhere, which is the hard prerequisite before any remote exposure of any of this.