Split out of #1423, which fixed the drift in one skill (using-agent-relay) and deliberately left the structural question alone. That PR is worth reading as the worked example — it demonstrates the failure mode rather than just describing it.
Problem
Six skills exist in three places with three different contents, and nothing reconciles them:
skill .claude/skills .agents/skills published (skills repo)
choosing-swarm-patterns 503 lines 438 lines 434 lines
relay-80-100-workflow 578 509 553
review-fix-signoff-loop 202 133 202
setting-up-relayfile 410 223 466
using-agent-relay 243 243 256
writing-agent-relay-workflows 2093 1523 2293
Every row has at least two distinct hashes. writing-agent-relay-workflows differs by ~630 lines between .claude and .agents even after normalizing markdown syntax — that is content divergence, not formatting. (.claude/skills has 19 skills, .agents/skills has 9, so the sets differ too.)
Why this needs a structural answer, not another sync
#1423 is the evidence. It opened planning to sync the vendored copies to the published skill, because the published one was correct on all four drift items. During the rebase, main independently fixed one of them and added new content the published copy doesn't have (the mode: "wait" vs "steer" injection guidance and get_message_readers).
So the direction of "which copy is canonical" reversed mid-PR. Had the original sync landed, it would have deleted main's improvements. The PR had to be rewritten to rebuild on main's version and re-apply only the surviving fixes.
That will keep happening. The copies are edited independently by different people and agents, and there is no signal when they diverge — so whichever one a given change lands in silently becomes "wrong" relative to the others.
The concrete cost isn't cosmetic. #1423's four drift items were: a security warning four minor versions stale that was suppressing working commands from the CLI reference, a wrong MCP tool prefix, a legacy engine URL, and a missing tool row that another skill actively tells agents to use.
Options
- Single source + generated vendored trees. Publish from the skills repo, generate
.claude/skills and .agents/skills, add a CI drift check. Vendored copies become read-only artifacts.
- Delete the vendored copies, rely on
npx prpm install. Smallest surface, but agents in a fresh checkout lose the skills until someone installs them.
- Keep hand-maintaining all three, and accept the drift as a known cost.
Option 1 is the obvious default, but it has a real prerequisite worth pricing before committing: the two trees are not currently identical by intent (.agents carries fewer skills and shorter files), so someone has to decide whether that difference is deliberate per-harness trimming or just accumulated staleness. If it's deliberate, generation needs a per-harness transform rather than a copy.
Note the skills repo has no root package.json and no CI workflows today, so option 1's drift check needs somewhere to run.
Acceptance
- One documented source of truth for each shared skill.
- Divergence is either impossible or fails a check, rather than being discovered during an unrelated rebase.
- The
.claude vs .agents content difference is either eliminated or documented as intentional with a mechanism that preserves it.
Refs #1423, AgentWorkforce/skills#89
Split out of #1423, which fixed the drift in one skill (
using-agent-relay) and deliberately left the structural question alone. That PR is worth reading as the worked example — it demonstrates the failure mode rather than just describing it.Problem
Six skills exist in three places with three different contents, and nothing reconciles them:
Every row has at least two distinct hashes.
writing-agent-relay-workflowsdiffers by ~630 lines between.claudeand.agentseven after normalizing markdown syntax — that is content divergence, not formatting. (.claude/skillshas 19 skills,.agents/skillshas 9, so the sets differ too.)Why this needs a structural answer, not another sync
#1423 is the evidence. It opened planning to sync the vendored copies to the published skill, because the published one was correct on all four drift items. During the rebase, main independently fixed one of them and added new content the published copy doesn't have (the
mode: "wait"vs"steer"injection guidance andget_message_readers).So the direction of "which copy is canonical" reversed mid-PR. Had the original sync landed, it would have deleted main's improvements. The PR had to be rewritten to rebuild on main's version and re-apply only the surviving fixes.
That will keep happening. The copies are edited independently by different people and agents, and there is no signal when they diverge — so whichever one a given change lands in silently becomes "wrong" relative to the others.
The concrete cost isn't cosmetic. #1423's four drift items were: a security warning four minor versions stale that was suppressing working commands from the CLI reference, a wrong MCP tool prefix, a legacy engine URL, and a missing tool row that another skill actively tells agents to use.
Options
.claude/skillsand.agents/skills, add a CI drift check. Vendored copies become read-only artifacts.npx prpm install. Smallest surface, but agents in a fresh checkout lose the skills until someone installs them.Option 1 is the obvious default, but it has a real prerequisite worth pricing before committing: the two trees are not currently identical by intent (
.agentscarries fewer skills and shorter files), so someone has to decide whether that difference is deliberate per-harness trimming or just accumulated staleness. If it's deliberate, generation needs a per-harness transform rather than a copy.Note the skills repo has no root
package.jsonand no CI workflows today, so option 1's drift check needs somewhere to run.Acceptance
.claudevs.agentscontent difference is either eliminated or documented as intentional with a mechanism that preserves it.Refs #1423, AgentWorkforce/skills#89