fix(init): clarify Codex desktop skill usage

.changeset/quiet-codex-skill-hint.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+Clarify the Codex setup hint for CLI, IDE, and desktop app users.

docs-lab/reference/supported-tools.md

@@ -80,8 +80,12 @@ Skills stay in `.cline/skills/`.
 
 ### Codex
 
-- **Invocation**: type `$openspec-<skill>`. Codex does not recognize the
-  `/openspec-<skill>` form ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **CLI and IDE extension**: type `$openspec-<skill>` or run `/skills`. Codex does
+  not recognize the `/openspec-<skill>` form
+  ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **Desktop app**: open Skills in the sidebar and select `openspec-<skill>`.
+  [OpenAI's skills documentation](https://learn.chatgpt.com/docs/build-skills)
+  describes both interfaces.
 - **No command files**: Codex runs skills directly, so init skips commands even when
   delivery includes them and prints `Commands skipped for: codex (uses skills)`.
 - **Shared folder**: Codex skills land in `.agents/skills/`, the same tree Antigravity,

src/core/init.ts

@@ -1360,9 +1360,13 @@ export class InitCommand {
           // Tools with no slash surface (e.g. Rovo Dev) reference skills as
           // prose ("the openspec-propose skill"); phrase the hint so it reads
           // as an instruction rather than a dead command with an argument.
-          hint = usesNaturalLanguageSkillReferences(tool.value)
-            ? `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`
-            : `Start your first change: ${skillReference} "your idea"`;
+          if (usesNaturalLanguageSkillReferences(tool.value)) {
+            hint = `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`;
+          } else if (tool.value === 'codex') {
+            hint = `Start your first change: ${skillReference} "your idea" (Codex CLI or IDE); in the Codex desktop app, select ${skillReference.slice(1)} from Skills in the sidebar`;
+          } else {
+            hint = `Start your first change: ${skillReference} "your idea"`;
+          }
         } else {
           continue;
         }

test/core/init.test.ts

@@ -2303,6 +2303,8 @@ describe('InitCommand - profile and detection features', () => {
     const logCalls = (console.log as unknown as { mock: { calls: unknown[][] } }).mock.calls.flat().map(String);
     const startHint = logCalls.find((entry) => entry.includes('Start your first change'));
     expect(startHint).toContain('$openspec-propose');
+    expect(startHint).toContain('(Codex CLI or IDE)');
+    expect(startHint).toContain('in the Codex desktop app, select openspec-propose from Skills in the sidebar');
     expect(startHint).not.toContain('/openspec-propose');
     expect(startHint).not.toContain('/opsx:propose');
 
@@ -2352,6 +2354,8 @@ describe('InitCommand - profile and detection features', () => {
     const codexHint = startHints.find((entry) => entry.includes('(Codex)'));
     const vibeHint = startHints.find((entry) => entry.includes('Mistral Vibe'));
     expect(codexHint).toContain('$openspec-propose');
+    expect(codexHint).toContain('(Codex CLI or IDE)');
+    expect(codexHint).toContain('Skills in the sidebar');
     expect(codexHint).not.toContain('/openspec-propose');
     expect(vibeHint).toContain('/openspec-propose');
     for (const hint of startHints) {