fix: map skill references for skills-only delivery

[Tylor110077]

Summary

• add transformToSkillReferences() for skills-only delivery
• wire the transformer in init and update
• add tests for command-reference transformation and skills-only init output

Testing

• npx vitest run test/utils/command-references.test.ts test/core/init.test.ts
• npm run build

Closes #879

Summary by CodeRabbit

• New Features
  • Enhanced SKILL.md generation to support skill references in skills delivery mode, mapping workflow identifiers to their corresponding skill references.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 112fd556-6f18-4e7f-b09b-d1475ffef060

📥 Commits

Reviewing files that changed from the base of the PR and between afdca0d and 5fb16bd.

📒 Files selected for processing (5)

• src/core/init.ts
• src/core/update.ts
• src/utils/command-references.ts
• test/core/init.test.ts
• test/utils/command-references.test.ts

---

📝 Walkthrough

Walkthrough

The PR fixes a bug where skills-only delivery mode generated SKILL.md files containing /opsx:* command references instead of /openspec-* skill namespace equivalents. It introduces a new transformer function that maps these hardcoded references to their corresponding skill cross-references and wires it into the skill generation flow.

Changes

Cohort / File(s)	Summary
Transformer Logic src/core/init.ts, src/core/update.ts	Updated SKILL.md generation to conditionally apply transformToSkillReferences for non-opencode tools when delivery === 'skills', replacing the hardcoded /opsx:* references with /openspec-* equivalents in generated skill files.
Command Reference Utilities src/utils/command-references.ts	Added OPSX_TO_SKILL_REFERENCE mapping object (8 workflow mappings) and new exported function transformToSkillReferences() that scans and replaces /opsx:<workflow> patterns with corresponding /openspec-* skill references.
Test Suite Updates test/core/init.test.ts, test/utils/command-references.test.ts	Updated delivery=skills test to expect /openspec-* references; added comprehensive test suite for transformToSkillReferences covering known/unknown workflow mappings and edge cases.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [Bug] Skills-only delivery emits /opsx:* command references #879 — This PR directly implements the proposed fix for the bug where skills-only delivery emitted /opsx:* command references instead of /openspec-* skill references by introducing transformToSkillReferences and wiring it into the skill generation flow.

Possibly related PRs

• fix(opencode): transform command references from colon to hyphen format #626 — Both PRs modify the command-reference transformation pipeline during skill generation by updating src/core/init.ts and src/core/update.ts to pass transformation callbacks; #626 adds transformToHyphenCommands for OpenCode while this PR extends that infrastructure with transformToSkillReferences for skills delivery mode.
• fix: use Skill tool for sync invocation in archive templates #632 — Both PRs replace /opsx:<workflow> cross-references with corresponding skill invocations (e.g., /opsx:apply → /openspec-apply-change), addressing reference namespace consistency in generated content.

Suggested reviewers

• TabishB

Poem

🐰 Cross-references once broken, now refine,
From /opsx: commands to skill designs divine,
Skills-only mode now gleams so bright,
With /openspec-* paths set right! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: mapping skill references for skills-only delivery mode, which directly addresses the bug fix.
Linked Issues check	✅ Passed	The PR fully implements the suggested fix from issue #879: adds transformToSkillReferences() function with explicit mapping, wires it into init/update paths when delivery==='skills', and validates with comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing issue #879: new transformer function, conditional integration in generation paths, and tests validating the fix. No unrelated changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[TabishB]

Hey @Tylor110077, thanks for digging into this! The bug is real and your fix correctly addresses the symptoms.

After reviewing, I want to flag something before we merge. The core issue here is that transformer selection logic has to be duplicated across init.ts and update.ts (3 places total), and the precedence between tool type and delivery mode is getting tricky to reason about (e.g., what should happen when the tool is OpenCode and delivery is skills-only?).

We have an existing change proposal called "unify-template-generation-pipeline" that was designed to solve exactly this class of problem. It introduces a first-class transform pipeline where each transform declares when it applies, so instead of duplicated ternaries we'd have a single declarative transform with an explicit applies(ctx) function. That would make the OpenCode vs. skills-only precedence question impossible to get wrong.

We're going to prioritize that change, and this fix would land naturally as part of it.

I don't want your work to go to waste though. Your mapping table (OPSX_TO_SKILL_REFERENCE) and the test cases are solid and will carry over directly into the unified pipeline. We'll reference this PR when we implement that piece.

Holding off on merging for now, but really appreciate you tracking this down and writing it up cleanly. 🙏

[stanleykao72]

Hi @TabishB, I found your comment about the unify-template-generation-pipeline really interesting.

I maintain a fork (stanleykao72/OpenSpec) where we've been running OpenSpec daily for an Odoo 18 Enterprise project. Over the past month, we hit the exact same "duplicated transformer logic" problem and ended up building a plugin system that solves it.

The key pieces:

1. composeTransformers() — chains multiple transformers (overlay + tool-specific + delivery-mode) into a single pipeline, replacing the duplicated ternaries in init.ts and update.ts.

2. Plugin manifests with skill_overlays — plugins declaratively inject content into generated skills at openspec update time. The transformer composition handles precedence automatically.

3. Lifecycle hooks — plugins register pre/post hooks at each phase boundary (propose, apply, verify, archive), enabling quality gates and custom validation without touching core code.

The fork has ~1,600 passing tests and has been production-tested across 150+ sessions.

Would the upstream be interested in a plugin system PR? I'm happy to extract the general-purpose parts (no domain-specific content) and submit it for review. The composeTransformers approach would naturally make @Tylor110077's skill-reference mapping work as a declarative transform rather than a hardcoded condition.

For reference, here's what the fork adds: 26 commits ahead of upstream/main

[TabishB]

@stanleykao72 Hey, that's super cool. I think I'd definitely be interested, but I'd need a better understanding of how each piece works. Let me take a look and get back to you.

[clay-good]

Closing as already fixed on main — thank you for the diagnosis, which was correct.

The bug this PR targets (#879) is closed as completed, and the fix is in the tree.

src/utils/command-references.ts on main contains exactly the mapping this PR proposed:

const COMMAND_TO_SKILL_NAME: Record<string, string> = {
  'explore': 'openspec-explore',
  'new': 'openspec-new-change',
  'continue': 'openspec-continue-change',
  'apply': 'openspec-apply-change',
  ...
};

function replaceCommandsWithSkillReferences(text: string, prefix: string): string {
  return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId: string) => {
    const skillName = COMMAND_TO_SKILL_NAME[commandId];
    return skillName === undefined ? match : `${prefix}${skillName}`;
  });
}

How it got there:

PR	Commit	What it did
#1194	b7c85c7 (2026-07-18)	Landed the transformer and wired it into init/update for skills-only delivery. Closed #879 and #881.
#1404	a84ae70 (2026-07-22)	Generalized the trigger from "delivery is skills-only" to "the tool has no command adapter" (CommandSurfaceCapability), fixing #1155 where Kimi/Vibe/Hermes shipped skills referencing /opsx:* commands that were never generated.

The shipped version also handles a case this PR did not: tools whose skill invocation prefix isn't / (Kimi uses /skill:<name>), via SKILL_INVOCATION_PREFIX.

Note this PR and #985 were duplicate fixes for the same issue — both are being closed for the same reason, with no reflection on either.

Reopen if you spot a path still emitting /opsx:* into a skills-only SKILL.md; that would be a live bug worth a fresh issue.