Context
The commonly behaviour skill exists as two tracked copies of the same file:
docs/agents/skills/commonly/SKILL.md — what README.md:142 and docs-site/agents/connect.mdx:51 tell users to drop into their own agent's skills directory
cli/skills/commonly/SKILL.md — what ships inside the npm package and what mountSkills mounts into agent workspaces
They are kept in sync by a publish hook in cli/package.json:
"prepublishOnly": "node -e \"require('fs').copyFileSync('../docs/agents/skills/commonly/SKILL.md','skills/commonly/SKILL.md')\""
This quietly makes the docs copy the real source of truth for the tarball, while the cli copy is the one contributors naturally edit (it sits next to the code that consumes it).
Why it matters — this already caused a shipped regression
PR #702 added the "post as yourself, never as your operator" guardrail — the fix for an agent posting under the operator's name — to the cli copy only. At publish time the hook copied the docs version over it, erasing the paragraph. @commonlyai/cli@0.1.4 shipped without the guardrail, so every agent attached with 0.1.4 was instructed without the rule that PR existed to add. Confirmed against the published tarball, not just the working tree.
Two properties combined to make it silent:
- the edit landed in the copy that is not the publish source
npm publish ships the working tree, not git HEAD, so the hook's overwrite also left the checkout dirty without anyone noticing
What #755 already did
- synced the guardrail into the docs copy so it actually ships (fixed in 0.1.5)
- added
cli/__tests__/skill-sync.test.mjs, which fails if the two copies drift
That makes the drift detectable. It does not make it impossible — there are still two files, the hook still silently overwrites a tracked file at publish, and a contributor editing the "wrong" one still has to be caught by CI rather than being unable to make the mistake.
Proposed fix
Pick one source of truth and remove the copy:
- Option A (preferred):
cli/skills/commonly/SKILL.md becomes canonical (it is the shipped runtime artifact and lives beside the code that mounts it). Delete docs/agents/skills/commonly/SKILL.md, drop prepublishOnly, and update README.md + docs-site/agents/connect.mdx to point at the packaged path — consistent with the repo's slim-anchor doc discipline in CLAUDE.md.
- Option B: keep docs canonical and stop tracking the cli copy, generating it at build time into a gitignored path.
Either way skill-sync.test.mjs can be retired, since drift becomes structurally impossible rather than merely tested for.
Scope note
Touches README.md and docs-site, so this was deliberately left out of #755 rather than done under deadline pressure.
Context
The commonly behaviour skill exists as two tracked copies of the same file:
docs/agents/skills/commonly/SKILL.md— whatREADME.md:142anddocs-site/agents/connect.mdx:51tell users to drop into their own agent's skills directorycli/skills/commonly/SKILL.md— what ships inside the npm package and whatmountSkillsmounts into agent workspacesThey are kept in sync by a publish hook in
cli/package.json:This quietly makes the docs copy the real source of truth for the tarball, while the cli copy is the one contributors naturally edit (it sits next to the code that consumes it).
Why it matters — this already caused a shipped regression
PR #702 added the "post as yourself, never as your operator" guardrail — the fix for an agent posting under the operator's name — to the cli copy only. At publish time the hook copied the docs version over it, erasing the paragraph.
@commonlyai/cli@0.1.4shipped without the guardrail, so every agent attached with 0.1.4 was instructed without the rule that PR existed to add. Confirmed against the published tarball, not just the working tree.Two properties combined to make it silent:
npm publishships the working tree, not git HEAD, so the hook's overwrite also left the checkout dirty without anyone noticingWhat #755 already did
cli/__tests__/skill-sync.test.mjs, which fails if the two copies driftThat makes the drift detectable. It does not make it impossible — there are still two files, the hook still silently overwrites a tracked file at publish, and a contributor editing the "wrong" one still has to be caught by CI rather than being unable to make the mistake.
Proposed fix
Pick one source of truth and remove the copy:
cli/skills/commonly/SKILL.mdbecomes canonical (it is the shipped runtime artifact and lives beside the code that mounts it). Deletedocs/agents/skills/commonly/SKILL.md, dropprepublishOnly, and updateREADME.md+docs-site/agents/connect.mdxto point at the packaged path — consistent with the repo's slim-anchor doc discipline inCLAUDE.md.Either way
skill-sync.test.mjscan be retired, since drift becomes structurally impossible rather than merely tested for.Scope note
Touches
README.mdanddocs-site, so this was deliberately left out of #755 rather than done under deadline pressure.