Skip to main content

skill-channel-rollout

Why It Exists​

This skill is the fourth of four deliverables in .omc/plans/skill-distribution-channels.md (local research artifact, not tracked in this repo): give next-starters' own skills a plugin marketplace and per-skill npm packages, then build "a repeatable rollout skill" so the same wiring can reach the rest of the fleet. The originating spec (.omc/specs/deep-interview-skill-distribution-channels.md, local research artifact) locked its boundary from round 5 of a 13-round interview: scaffold and wire, but the actual first npm publish is always a human action, never something the skill does itself.

It didn't stay theoretical. The same session that landed it (ddeb5f5) ran it for real against seven sibling repos — ng-starters, lighthouse, cates-works, client-os, offerly, mcp-agent-bridge, and cogs — and each one surfaced genuinely different mess the skill had to detect rather than paper over: ng-starters had no package.json at all yet; lighthouse needed pnpm bumped 9.15.0→10.33.0 before pnpm pack --dry-run would even run; client-os and offerly needed broken reference paths fixed; offerly needed a skill directory renamed to match its own SKILL.md frontmatter; mcp-agent-bridge needed a packages: glob added to a pre-existing but empty pnpm-workspace.yaml. cogs was the sharpest edge case — it already ran its own hardened, OIDC-based release pipeline with an explicit banner against merging in a second workflow, so the rollout there skipped the default scaffold and instead merged additively into cogs' own release script and .changeset/config.json (docs/sessions/2026-08-14-skill-distribution-rollout/adr/0001-reuse-cogs-existing-release-pipeline.md). A real crash bug — an uncaught ENOENT in generate-skill-package-json.mjs when a skill's metadata.json was missing — was hit live across three of those repos, fixed in 58ccfeb, and republished as @next-starters/skill-skill-channel-rollout@1.0.1 in 9907a67.

What It Does​

Given a target repo path, the skill first checks whether that repo is pnpm-managed and free of a stale package.json "workspaces" field — surfacing either problem instead of silently choosing a package manager or letting a leftover field silently outrank the pnpm-workspace.yaml it's about to write. It then asks, one AskUserQuestion call at a time, for the target's npm scope and plugin command prefix, and scaffolds the same pipeline next-starters runs on itself: pnpm-workspace.yaml, two release scripts, packages/.gitignore, five self-contained bin/*.mjs pipeline scripts, .changeset/config.json, a docs/published-skills.json allowlist, and a full .github/workflows/skills-release.yml job skeleton.

Every scaffolded file is write-if-absent — an existing file is reported as skipped, never overwritten — and the skill also runs a reference- normalization check against the target's own skills/*/metadata.json, reporting anomalies without fixing any of them. It never invokes npm publish, changeset publish, or --publish anywhere; that first publish is always left to a human, in the target repo, on their own schedule.

How To Use It​

Triggers on: "roll out the skill distribution pattern", "scaffold the skill release pipeline into <repo>", "add skill channels to another repo", "replicate skill-channel-rollout", "pnpm workspace for skill packages in a new repo", or bringing this repo's npm/marketplace publishing pattern to a sibling repo.

skills add git@github.com:catesandrew/next-starters.git --skill skills/skill-channel-rollout -g
npm install @next-starters/skill-skill-channel-rollout
/plugin marketplace add catesandrew/next-starters
/plugin install skill-channel-rollout@next-starters

Gotchas & Invariants​

  • The package-manager gate runs first and never silently resolves — a non-pnpm repo, mixed lockfiles, or no package.json at all (a real case: ng-starters had none) stops scaffolding and asks via AskUserQuestion instead of guessing.
  • A stale npm/yarn-style "workspaces" field in the target's package.json is checked for before pnpm-workspace.yaml is written — @manypkg/get- packages (which Changesets uses for package discovery) checks that field first, so a leftover value would silently outrank the new file and break discovery with no error until a confusing "no packages found" much later.
  • npm scope and plugin command prefix are asked as two separate AskUserQuestion calls, never bundled, never defaulted — both feed content that's expensive to rename later.
  • Nothing scaffolded ever overwrites an existing file; an already-present path is reported as skipped. Running the skill twice against the same target produces identical output.
  • The five bin/*.mjs pipeline scripts are copied as full, self-contained implementations from this skill's own references/, not as thin wrappers pointing back at next-starters' own bin/ directory — that directory won't exist once this skill ships as a standalone npm/plugin package elsewhere.
  • Reference-normalization anomalies in the target's skills/*/metadata.json are printed, never auto-fixed — deciding whether a flagged reference is real package content or repo-only tooling is a per-skill human judgment call this skill can't make for someone else's repo.
  • The default scaffold assumes no existing release pipeline. cogs already had one (hardened, OIDC-based, with an explicit no-merge banner), so its rollout deliberately skipped the new workflow file and merged the sync steps additively into cogs' existing release script instead — a real precedent for repos that already publish something.
  • This skill never runs npm publish, changeset publish, or any --publish flag, under any circumstance — not as a dry-run confirmation, not if asked to "go ahead and publish it." That step is always a separate, deliberate, human-run action in the target repo.

This skill doesn't have a close sibling in this catalog — it's the only one about replicating next-starters' own distribution pattern into another repo.

Sourced from: skills/skill-channel-rollout/metadata.json, skills/skill-channel-rollout/SKILL.md, .omc/plans/skill-distribution-channels.md (local research artifact, not tracked in this repo), .omc/specs/deep-interview-skill-distribution-channels.md (local research artifact, not tracked in this repo), docs/sessions/2026-08-14-skill-distribution-rollout/SUMMARY.md, docs/sessions/2026-08-14-skill-distribution-rollout/README.md, docs/sessions/2026-08-14-skill-distribution-rollout/FOLLOWUPS.md, docs/sessions/2026-08-14-skill-distribution-rollout/adr/0001-reuse-cogs-existing-release-pipeline.md, git log --follow -- skills/skill-channel-rollout (commits ddeb5f5, 58ccfeb, 9907a67)