When an AI collaboration repo corrupts its own source of truth

As teams bring AI agents into daily engineering, a few prompts quickly become a shared repository of Skills, Plugins, team rules, project entry points, operating procedures, and accumulated advice.

The repository I governed followed the same path. Every new problem made another rule or Skill look reasonable. Over time, the repo began to corrupt the single source of truth it was meant to protect.

Background

The repo coordinated working methods across several teams and AI agents. It contained company-wide contracts, internal team actions, external interfaces, capability lifecycle rules, and optional productivity methods.

Unlike documentation that humans read occasionally, these files enter agent context and directly affect behavior. Every additional entity therefore has a continuing cost: maintenance, conflicts with other rules, larger context, diluted attention, and less predictable behavior when instructions disagree.

The right question was not merely whether a document contained useful information. Its behavioral value had to exceed its long-term cost.

Pain

Competing sources of truth

One rule could appear in a Team Contract, a Skill, a README, a static project map, and an operating guide. Once one copy changed, the projections drifted. Agents received several plausible but incompatible versions without knowing which one was authoritative.

Different capability types shared one governance model

Mandatory company contracts, team-facing interfaces, internal procedures, and personal productivity tips were all treated as equivalent Skills. Optional advice looked mandatory, while team-local actions appeared to apply company-wide.

The repo reimplemented native platform capabilities

It maintained its own discovery, installation, update, review, and release rules even where Codex Plugin/Skill tooling, GitHub Issue/PR workflows, and release contracts already provided the mechanism. The duplicate lifecycle added maintenance without unique behavior.

More context did not prove greater reliability

Before cleanup, 22 SKILL.md files contained 2,975 lines. Their volume kept growing, but there was no evidence that every section made agents faster or more correct.

Response

Use a deletion counterfactual

For every entity, I asked:

If this disappears, will the agent act incorrectly or become meaningfully slower?

If neither changed, the entity should not remain an independent Skill. Unique behavior moved to its canonical home; duplicated text was removed rather than preserved behind another forwarding layer.

Separate five capability classes

I rebuilt the capability map around five distinct responsibilities:

1. Skill lifecycle — one entry point for Find, Adopt, Contribute, and Release;
2. Company contracts — shared sources of truth, authority, state, and delivery boundaries;
3. Team external interfaces — public inputs, visible state, outputs, and acceptance;
4. Team internal contracts and actions — decisions and operating boundaries inside one domain;
5. Adhoc productivity capabilities — optional methods that do not become mandatory contracts.

This was an ownership and authority model, not just a folder taxonomy.

Introduce common admission gates

Every formal Skill now has to satisfy the same nine invariant gates covering responsibility, sources of truth, authority, state semantics, and delivery evidence. A capability that cannot pass remains on HOLD rather than entering team context because it might be useful someday.

Delegate mechanisms to native tools

Codex Plugin commands own discovery, installation, removal, and readback. GitHub Issues and PRs hold implementation and review evidence. Release contracts hold publication state. The shared repo retains the company’s unique WHAT, decision boundaries, and routing logic.

Results

The quantitative comparison is deliberately scoped to plugins/*/skills/*/SKILL.md:

Metric	Before	After	Change
Skill instruction lines	2,975	1,437	-51.7%
Skill count	22	18	-18.2%

Nine Skills were removed, while additions and mergers produced five capabilities. The net reduction was 1,538 lines. Most of the saving came from slimming retained Skills, not merely deleting directories.

The source refactor passed 98 tests, and all 18 Skill folders passed independent validation. More importantly, the repo now has explicit sources of truth, projections, and capability ownership. Company rules, team interfaces, and personal methods no longer compete for the same authoritative position.

I do not present this as a quantified productivity improvement. There is not enough evidence for such a claim. What the evidence supports is a governance result: contradictory context was removed, agents receive fewer and clearer rules, and every shared capability now has a testable admission and lifecycle model.

For an AI collaboration system, more context is not automatically more capability. The durable value comes from fewer conflicts, clearer authority, and requiring every rule to explain which behavior it actually changes.