fix: use skill references in SKILL.md for skills-only delivery

.changeset/skills-only-references.md

@@ -0,0 +1,5 @@
+---
+'@fission-ai/openspec': patch
+---
+
+Fix skills-only delivery emitting `/opsx:*` command references. SKILL.md files generated by init, update, and workspace skill setup now reference the corresponding skills (e.g. `/openspec-apply-change`) when `delivery: 'skills'` is configured, instead of commands that were never generated.

src/core/init.ts

@@ -13,7 +13,7 @@ import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
+import { getTransformerForTool } from '../utils/command-references.js';
 import {
   AI_TOOLS,
   OPENSPEC_DIR_NAME,
@@ -566,8 +566,7 @@ export class InitCommand {
             const skillFile = path.join(skillDir, 'SKILL.md');
 
             // Generate SKILL.md content with YAML frontmatter including generatedBy
-            // Use hyphen-based command references for tools where filename = command name
-            const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+            const transformer = getTransformerForTool(tool.value, delivery);
             const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
 
             // Write the skill file

src/core/update.ts

@@ -11,7 +11,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
+import { getTransformerForTool } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import {
   generateCommands,
@@ -196,8 +196,7 @@ export class UpdateCommand {
             const skillDir = path.join(skillsDir, dirName);
             const skillFile = path.join(skillDir, 'SKILL.md');
 
-            // Use hyphen-based command references for OpenCode
-            const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+            const transformer = getTransformerForTool(tool.value, delivery);
             const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
             await FileSystemUtils.writeFile(skillFile, skillContent);
           }
@@ -690,8 +689,7 @@ export class UpdateCommand {
             const skillDir = path.join(skillsDir, dirName);
             const skillFile = path.join(skillDir, 'SKILL.md');
 
-            // Use hyphen-based command references for OpenCode
-            const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+            const transformer = getTransformerForTool(tool.value, delivery);
             const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
             await FileSystemUtils.writeFile(skillFile, skillContent);
           }

src/utils/command-references.ts

@@ -18,3 +18,68 @@
 export function transformToHyphenCommands(text: string): string {
   return text.replace(/\/opsx:/g, '/opsx-');
 }
+
+/**
+ * Maps command short names to their skill directory references.
+ * Keep in sync with WORKFLOW_TO_SKILL_DIR, which exists in both
+ * src/core/profile-sync-drift.ts (exported) and src/core/init.ts (local copy).
+ */
+const COMMAND_TO_SKILL_REFERENCE: Record<string, string> = {
+  'explore': '/openspec-explore',
+  'new': '/openspec-new-change',
+  'continue': '/openspec-continue-change',
+  'apply': '/openspec-apply-change',
+  'ff': '/openspec-ff-change',
+  'sync': '/openspec-sync-specs',
+  'archive': '/openspec-archive-change',
+  'bulk-archive': '/openspec-bulk-archive-change',
+  'verify': '/openspec-verify-change',
+  'onboard': '/openspec-onboard',
+  'propose': '/openspec-propose',
+};
+
+/**
+ * Transforms command references to skill references for skills-only delivery.
+ * Converts `/opsx:<command>` patterns to `/openspec-<skill>` so that
+ * generated skills do not reference commands that were never generated.
+ *
+ * Unknown command references are left unchanged.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to skill references
+ *
+ * @example
+ * transformToSkillReferences('/opsx:apply') // returns '/openspec-apply-change'
+ * transformToSkillReferences('Use /opsx:archive next') // returns 'Use /openspec-archive-change next'
+ */
+export function transformToSkillReferences(text: string): string {
+  return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId: string) => {
+    return COMMAND_TO_SKILL_REFERENCE[commandId] ?? match;
+  });
+}
+
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skills-only delivery always uses skill references — for every tool — so
+ * generated skills never point at commands that were not generated. When
+ * commands are generated, tools where the command filename doubles as the
+ * command name (opencode, pi) use hyphen-based command references. All other
+ * cases keep the default `/opsx:*` references.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @returns The transformer to pass to generateSkillContent, or undefined
+ */
+export function getTransformerForTool(
+  toolId: string,
+  delivery: 'both' | 'skills' | 'commands'
+): ((text: string) => string) | undefined {
+  if (delivery === 'skills') {
+    return transformToSkillReferences;
+  }
+  if (toolId === 'opencode' || toolId === 'pi') {
+    return transformToHyphenCommands;
+  }
+  return undefined;
+}

src/utils/index.ts

@@ -15,4 +15,8 @@ export {
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 
 // Command reference utilities
-export { transformToHyphenCommands } from './command-references.js';
+export {
+  transformToHyphenCommands,
+  transformToSkillReferences,
+  getTransformerForTool,
+} from './command-references.js';

test/core/init.test.ts

@@ -717,6 +717,31 @@ describe('InitCommand - profile and detection features', () => {
     // Commands should NOT exist
     const cmdFile = path.join(testDir, '.claude', 'commands', 'opsx', 'explore.md');
     expect(await fileExists(cmdFile)).toBe(false);
+
+    // Skill content should reference skills, not commands that were never generated
+    const skillContent = await fs.readFile(skillFile, 'utf-8');
+    expect(skillContent).not.toContain('/opsx:');
+    expect(skillContent).toContain('/openspec-');
+  });
+
+  it('should use skill references for opencode in skills-only delivery', async () => {
+    saveGlobalConfig({
+      featureFlags: {},
+      profile: 'core',
+      delivery: 'skills',
+    });
+
+    const initCommand = new InitCommand({ tools: 'opencode', force: true });
+    await initCommand.execute(testDir);
+
+    const skillFile = path.join(testDir, '.opencode', 'skills', 'openspec-explore', 'SKILL.md');
+    expect(await fileExists(skillFile)).toBe(true);
+
+    // Skills-only must win over the hyphen transform: no /opsx: or /opsx- references
+    const skillContent = await fs.readFile(skillFile, 'utf-8');
+    expect(skillContent).not.toContain('/opsx:');
+    expect(skillContent).not.toContain('/opsx-');
+    expect(skillContent).toContain('/openspec-');
   });
 
   it('should respect delivery=commands setting (no skills)', async () => {

test/core/update.test.ts

@@ -1485,6 +1485,14 @@ More user content after markers.
       expect(await FileSystemUtils.fileExists(
         path.join(commandsDir, 'explore.md')
       )).toBe(false);
+
+      // Skill content should reference skills, not commands that were never generated
+      const skillContent = await fs.readFile(
+        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
+        'utf-8'
+      );
+      expect(skillContent).not.toContain('/opsx:');
+      expect(skillContent).toContain('/openspec-');
     });
 
     it('should respect commands-only delivery setting', async () => {

test/utils/command-references.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import { transformToHyphenCommands } from '../../src/utils/command-references.js';
+import {
+  getTransformerForTool,
+  transformToHyphenCommands,
+  transformToSkillReferences,
+} from '../../src/utils/command-references.js';
 
 describe('transformToHyphenCommands', () => {
   describe('basic transformations', () => {
@@ -81,3 +85,104 @@ Finally /opsx-apply to implement`;
     }
   });
 });
+
+describe('transformToSkillReferences', () => {
+  describe('all known commands', () => {
+    const mappings: Array<[string, string]> = [
+      ['explore', '/openspec-explore'],
+      ['new', '/openspec-new-change'],
+      ['continue', '/openspec-continue-change'],
+      ['apply', '/openspec-apply-change'],
+      ['ff', '/openspec-ff-change'],
+      ['sync', '/openspec-sync-specs'],
+      ['archive', '/openspec-archive-change'],
+      ['bulk-archive', '/openspec-bulk-archive-change'],
+      ['verify', '/openspec-verify-change'],
+      ['onboard', '/openspec-onboard'],
+      ['propose', '/openspec-propose'],
+    ];
+
+    for (const [cmd, skillRef] of mappings) {
+      it(`should transform /opsx:${cmd} to ${skillRef}`, () => {
+        expect(transformToSkillReferences(`/opsx:${cmd}`)).toBe(skillRef);
+      });
+    }
+  });
+
+  describe('basic transformations', () => {
+    it('should transform command reference in context', () => {
+      const input = 'Use /opsx:apply to implement tasks';
+      const expected = 'Use /openspec-apply-change to implement tasks';
+      expect(transformToSkillReferences(input)).toBe(expected);
+    });
+
+    it('should transform multiple command references', () => {
+      const input = 'Run /opsx:apply then /opsx:archive';
+      const expected = 'Run /openspec-apply-change then /openspec-archive-change';
+      expect(transformToSkillReferences(input)).toBe(expected);
+    });
+
+    it('should handle backtick-quoted commands', () => {
+      const input = 'Run `/opsx:continue` to proceed';
+      const expected = 'Run `/openspec-continue-change` to proceed';
+      expect(transformToSkillReferences(input)).toBe(expected);
+    });
+
+    it('should transform references across multiple lines', () => {
+      const input = `Use /opsx:new to start
+Then /opsx:apply to implement`;
+      const expected = `Use /openspec-new-change to start
+Then /openspec-apply-change to implement`;
+      expect(transformToSkillReferences(input)).toBe(expected);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should return unchanged text with no command references', () => {
+      const input = 'This is plain text without commands';
+      expect(transformToSkillReferences(input)).toBe(input);
+    });
+
+    it('should return empty string unchanged', () => {
+      expect(transformToSkillReferences('')).toBe('');
+    });
+
+    it('should leave unknown command references unchanged', () => {
+      const input = 'Try /opsx:unknown-command here';
+      expect(transformToSkillReferences(input)).toBe(input);
+    });
+
+    it('should not transform similar but non-matching patterns', () => {
+      const input = '/ops:new opsx: /other:command';
+      expect(transformToSkillReferences(input)).toBe(input);
+    });
+
+    it('should transform longest matching command (bulk-archive vs archive)', () => {
+      const input = '/opsx:bulk-archive and /opsx:archive';
+      const expected = '/openspec-bulk-archive-change and /openspec-archive-change';
+      expect(transformToSkillReferences(input)).toBe(expected);
+    });
+  });
+});
+
+describe('getTransformerForTool', () => {
+  it('selects skill references for skills-only delivery for every tool', () => {
+    expect(getTransformerForTool('claude', 'skills')).toBe(transformToSkillReferences);
+    expect(getTransformerForTool('codex', 'skills')).toBe(transformToSkillReferences);
+    // opencode/pi must not fall back to hyphen commands when no commands are generated
+    expect(getTransformerForTool('opencode', 'skills')).toBe(transformToSkillReferences);
+    expect(getTransformerForTool('pi', 'skills')).toBe(transformToSkillReferences);
+  });
+
+  it('selects hyphen commands for opencode and pi when commands are generated', () => {
+    expect(getTransformerForTool('opencode', 'both')).toBe(transformToHyphenCommands);
+    expect(getTransformerForTool('opencode', 'commands')).toBe(transformToHyphenCommands);
+    expect(getTransformerForTool('pi', 'both')).toBe(transformToHyphenCommands);
+    expect(getTransformerForTool('pi', 'commands')).toBe(transformToHyphenCommands);
+  });
+
+  it('selects no transformer for other tools when commands are generated', () => {
+    expect(getTransformerForTool('claude', 'both')).toBeUndefined();
+    expect(getTransformerForTool('claude', 'commands')).toBeUndefined();
+  });
+});