docs(skills): add provider-specific override references

Author: Waishnav

skills/subagents/references/claude.md

@@ -0,0 +1,20 @@
+# Claude overrides
+
+DevSpace passes `--model` to the Claude Agent SDK. When `--effort` is present,
+DevSpace passes the SDK effort value with adaptive thinking enabled.
+
+The SDK effort vocabulary is:
+
+- `low`
+- `medium`
+- `high`
+- `xhigh`
+- `max`
+
+Support is model-dependent. Some Claude models expose only part of this set or
+do not support the effort option. Prefer configured defaults and omit an
+override when the selected model's capability is unknown.
+
+```bash
+devspace agents run claude --model <model> --effort <supported-level> "<brief>"
+```

skills/subagents/references/codex.md

@@ -0,0 +1,19 @@
+# Codex overrides
+
+DevSpace passes `--model` to the Codex SDK and maps `--effort` to model
+reasoning effort.
+
+The SDK accepts these effort labels:
+
+- `minimal`
+- `low`
+- `medium`
+- `high`
+- `xhigh`
+
+The selected model may support only a subset. Prefer the profile or provider
+default. Omit `--effort` when the exact model capability is unknown.
+
+```bash
+devspace agents run codex --model <model> --effort <supported-level> "<brief>"
+```

skills/subagents/references/copilot.md

@@ -0,0 +1,12 @@
+# Copilot overrides
+
+DevSpace connects to Copilot through ACP. `--model` selects the ACP `model`
+option and `--effort` selects the ACP `thought_level` option.
+
+Both option sets are announced by the running Copilot ACP session and may vary
+by version or account. Do not invent a value. Omit the override unless the user
+provided an exact value known to that Copilot installation.
+
+```bash
+devspace agents run copilot --model <exact-model> --effort <exact-thought-level> "<brief>"
+```

skills/subagents/references/cursor.md

@@ -0,0 +1,12 @@
+# Cursor overrides
+
+DevSpace connects to Cursor through ACP. `--model` selects the ACP `model`
+option and `--effort` selects the ACP `thought_level` option.
+
+Both option sets are announced by the running Cursor ACP session and may vary
+by version or account. Do not invent a value. Omit the override unless the user
+provided an exact value known to that Cursor installation.
+
+```bash
+devspace agents run cursor --model <exact-model> --effort <exact-thought-level> "<brief>"
+```

skills/subagents/references/opencode.md

@@ -0,0 +1,12 @@
+# OpenCode overrides
+
+DevSpace passes `--model` to OpenCode. A model may be written as
+`<provider>/<model>` when the OpenCode provider id is needed.
+
+DevSpace maps `--effort` to the OpenCode model `variant` field. Variant names
+are model-specific; there is no safe global effort list. Omit `--effort` unless
+the exact variant is already known from the user's configuration or request.
+
+```bash
+devspace agents run opencode --model <provider/model> --effort <exact-variant> "<brief>"
+```

skills/subagents/references/pi.md

@@ -0,0 +1,20 @@
+# Pi overrides
+
+DevSpace passes `--model` to Pi and maps `--effort` to Pi's native
+`--thinking` option.
+
+Pi accepts these thinking labels:
+
+- `off`
+- `minimal`
+- `low`
+- `medium`
+- `high`
+- `xhigh`
+
+Pi applies model-specific capability rules, so a selected model may expose or
+honor only a subset. Prefer the profile or provider default when uncertain.
+
+```bash
+devspace agents run pi --model <model> --effort <supported-level> "<brief>"
+```

src/skills.test.ts

@@ -208,6 +208,17 @@ try {
     ),
     true,
   );
+  const subagentsSkill = loadWorkspaceSkills(experimentalConfig, projectRoot).skills.find(
+    (skill) => skill.name === "subagents",
+  );
+  assert.ok(subagentsSkill);
+  const codexReference = join(subagentsSkill.baseDir, "references", "codex.md");
+  assert.equal(resolveSkillReadPath([subagentsSkill], new Set(), codexReference), undefined);
+  assert.equal(
+    resolveSkillReadPath([subagentsSkill], new Set([subagentsSkill.baseDir]), codexReference)
+      ?.absolutePath,
+    codexReference,
+  );
 
   const duplicateConfig = loadConfig({
     DEVSPACE_ALLOWED_ROOTS: projectRoot,