Skip to content

Collapse the duplicated commonly skill to a single source of truth #756

Description

@lilyshen0722

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:

  1. the edit landed in the copy that is not the publish source
  2. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions