fix(sdk): warn for silently dropped skill, command, and hook options (#8)

Author: arielarevalo

.tegami/2026-09-01-unsupported-option-warnings.md

@@ -0,0 +1,8 @@
+---
+packages:
+  "@jalco/ap-sdk": patch
+---
+
+### Warn for silently dropped skill, command, and hook options
+
+Emitters that cannot represent a declared optional field now record an `unsupported-option` warning instead of dropping the field silently, the same contract the Codex subagent warnings already followed. This covers `allowedTools`, `disableModelInvocation`, `license`, and `metadata` on skills, `allowedTools`, `argumentHint`, and passthrough `frontmatter` on commands, and the `powershell` hook command variant on harnesses with a single command slot. Output files are unchanged: the build still degrades, and `warnings[]` now tells the caller what was lost.

apps/docs/content/docs/commands.mdx

@@ -35,9 +35,9 @@ export default definePlugin({
 
 ## Fields
 
-- `name`, `description`, `argumentHint`, and `body` define the command.
-- `allowedTools` is honored by Claude Code.
-- `frontmatter` is honored by YAML-frontmatter harnesses; Gemini TOML and Cursor plain markdown ignore it.
+- `name`, `description`, `argumentHint`, and `body` define the command. `argumentHint` is emitted on Claude Code, Codex, Pi, and Copilot. The other harnesses drop it with an `unsupported-option` warning.
+- `allowedTools` is honored by Claude Code. Codex, Pi, OpenCode, Gemini, Cursor, and Windsurf drop it with an `unsupported-option` warning. The Copilot emitter does not emit it yet.
+- `frontmatter` is honored by YAML-frontmatter harnesses. Gemini TOML and Cursor plain markdown drop it with an `unsupported-option` warning.
 - `harness.claude.model`, `harness.opencode.model`, and `harness.copilot.model` / `agent` set native model hints.
 
 ## Portability notes

apps/docs/content/docs/hooks.mdx

@@ -15,7 +15,7 @@ export default definePlugin({
     defineHook({
       event: "pre-tool-use",
       matcher: "ExitPlanMode",
-      command: { unix: "node hooks/plan-review.mjs", powershell: "node hooks/plan-review.mjs" },
+      command: { bash: "node hooks/plan-review.mjs", powershell: "node hooks/plan-review.mjs" },
       timeout: 120,
       async: true,
       harness: { codex: { event: "stop", matcher: undefined } },
@@ -43,7 +43,7 @@ export default definePlugin({
 
 - `event`, `matcher`, `command`, and `timeout` define the hook.
 - `async` is native in Claude and dropped with a warning elsewhere.
-- Object commands can provide `unix` and `powershell`; PowerShell is used by Copilot.
+- Object commands can provide `bash` and `powershell`. Copilot emits the PowerShell variant as `windows`. Claude Code, Codex, and Gemini have a single command slot, so they use `bash` and drop `powershell` with an `unsupported-option` warning.
 - `harness.<target>.event` and `matcher` override native mapping. Use `matcher: undefined` to explicitly clear a matcher.
 
 <Callout variant="note" title="Code-only harnesses">

apps/docs/content/docs/skills.mdx

@@ -31,10 +31,10 @@ export default definePlugin({
 - `name` — kebab-case id, max 64 characters.
 - `description` — max 1024 characters, the tightest harness limit; front-load trigger conditions because agents use this to decide when to load the skill.
 - `instructions` — the skill body.
-- `allowedTools` — honored by Claude Code and Pi.
-- `disableModelInvocation` — Pi-specific.
-- `license` — emitted where native skill metadata supports it.
-- `metadata` — honored by OpenCode and Pi.
+- `allowedTools` — honored by Claude Code and Pi. Other skill-capable harnesses drop it with an `unsupported-option` warning.
+- `disableModelInvocation` — honored by Pi and Copilot. Codex, OpenCode, Gemini, and Windsurf drop it with an `unsupported-option` warning.
+- `license` — emitted where native skill metadata supports it (Pi, OpenCode). Codex, Copilot, Gemini, and Windsurf drop it with an `unsupported-option` warning.
+- `metadata` — honored by OpenCode and Pi. Copilot, Gemini, and Windsurf drop it with an `unsupported-option` warning.
 - `frontmatter` — escape hatch merged into YAML-frontmatter harnesses; SDK-owned fields win on conflicts.
 - `resources` — extra files emitted inside the skill directory.
 

packages/agent-plugin-sdk/src/harnesses/codex.ts

@@ -9,6 +9,10 @@ import {
   emitContextFile,
   emitSkillDir,
   json,
+  warnCommandAllowedTools,
+  warnSkillAllowedTools,
+  warnSkillDisableModelInvocation,
+  warnSkillLicense,
 } from "./shared.js";
 import { toCodexEntry } from "./mcp.js";
 import { buildMatcherHooks } from "./hooks.js";
@@ -79,6 +83,11 @@ export const codex: Harness = {
         name: skill.name,
         description: skill.description,
       };
+      if (skill.allowedTools?.length)
+        warnSkillAllowedTools(ctx, "codex", skill.name);
+      if (skill.disableModelInvocation)
+        warnSkillDisableModelInvocation(ctx, "codex", skill.name);
+      if (skill.license) warnSkillLicense(ctx, "codex", skill.name);
       files.push(...emitSkillDir(skill, frontmatter, "skills"));
     }
 
@@ -92,6 +101,8 @@ export const codex: Harness = {
         description: command.description,
         "argument-hint": command.argumentHint,
       });
+      if (command.allowedTools?.length)
+        warnCommandAllowedTools(ctx, "codex", command.name);
       files.push(
         emitCommandFile(
           command.name,

packages/agent-plugin-sdk/src/harnesses/copilot.ts

@@ -3,7 +3,14 @@ import { join } from "node:path";
 import type { OutputFile, Plugin } from "../types.js";
 import { compact, mapValues, mergeFrontmatter, renderFrontmatterDoc } from "../util/frontmatter.js";
 import type { EmitContext, Harness, InstallScope } from "./types.js";
-import { emitContextFile, emitSkillDir, json } from "./shared.js";
+import {
+  emitContextFile,
+  emitSkillDir,
+  json,
+  warnSkillAllowedTools,
+  warnSkillLicense,
+  warnSkillMetadata,
+} from "./shared.js";
 import { toCopilotEntry } from "./mcp.js";
 import { buildCopilotHooks } from "./hooks.js";
 import { mcpServerEntry, toolServerMcp } from "./tools.js";
@@ -56,6 +63,11 @@ export const copilot: Harness = {
         description: skill.description,
         "disable-model-invocation": skill.disableModelInvocation || undefined,
       });
+      if (skill.allowedTools?.length)
+        warnSkillAllowedTools(ctx, "copilot", skill.name);
+      if (skill.license) warnSkillLicense(ctx, "copilot", skill.name);
+      if (skill.metadata && Object.keys(skill.metadata).length > 0)
+        warnSkillMetadata(ctx, "copilot", skill.name);
       files.push(...emitSkillDir(skill, frontmatter, ".github/skills"));
     }
 

packages/agent-plugin-sdk/src/harnesses/cursor.ts

@@ -2,8 +2,14 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { OutputFile, Plugin } from "../types.js";
 import { compact, mapValues } from "../util/frontmatter.js";
-import type { Harness, InstallScope } from "./types.js";
-import { emitContextFile, json } from "./shared.js";
+import type { EmitContext, Harness, InstallScope } from "./types.js";
+import {
+  emitContextFile,
+  json,
+  warnCommandAllowedTools,
+  warnCommandArgumentHint,
+  warnCommandFrontmatter,
+} from "./shared.js";
 import { toCursorEntry } from "./mcp.js";
 import { mcpServerEntry, toolServerMcp } from "./tools.js";
 
@@ -47,7 +53,7 @@ export const cursor: Harness = {
 
   contextFileName: "AGENTS.md",
 
-  emit(plugin: Plugin): OutputFile[] {
+  emit(plugin: Plugin, ctx: EmitContext): OutputFile[] {
     const files: OutputFile[] = [];
 
     if (plugin.instructions?.trim()) {
@@ -60,6 +66,12 @@ export const cursor: Harness = {
     // slash-command name; Cursor appends the user's input, so the body is passed
     // through untouched.
     for (const command of plugin.commands ?? []) {
+      if (command.argumentHint)
+        warnCommandArgumentHint(ctx, "cursor", command.name);
+      if (command.allowedTools?.length)
+        warnCommandAllowedTools(ctx, "cursor", command.name);
+      if (command.frontmatter && Object.keys(command.frontmatter).length > 0)
+        warnCommandFrontmatter(ctx, "cursor", command.name);
       files.push({
         path: `.cursor/commands/${command.name}.md`,
         content: command.body.trimEnd() + "\n",

packages/agent-plugin-sdk/src/harnesses/gemini.ts

@@ -10,6 +10,13 @@ import {
   hasPositionalArgs,
   json,
   rewriteArgsToGemini,
+  warnCommandAllowedTools,
+  warnCommandArgumentHint,
+  warnCommandFrontmatter,
+  warnSkillAllowedTools,
+  warnSkillDisableModelInvocation,
+  warnSkillLicense,
+  warnSkillMetadata,
 } from "./shared.js";
 import { toGeminiEntry } from "./mcp.js";
 import { buildMatcherHooks } from "./hooks.js";
@@ -96,6 +103,13 @@ export const gemini: Harness = {
         name: skill.name,
         description: skill.description,
       });
+      if (skill.allowedTools?.length)
+        warnSkillAllowedTools(ctx, "gemini", skill.name);
+      if (skill.disableModelInvocation)
+        warnSkillDisableModelInvocation(ctx, "gemini", skill.name);
+      if (skill.license) warnSkillLicense(ctx, "gemini", skill.name);
+      if (skill.metadata && Object.keys(skill.metadata).length > 0)
+        warnSkillMetadata(ctx, "gemini", skill.name);
       files.push(...emitSkillDir(skill, frontmatter, "skills"));
     }
 
@@ -115,6 +129,12 @@ export const gemini: Harness = {
             "Gemini commands only support `{{args}}` (all arguments); positional tokens are left literal.",
         });
       }
+      if (command.argumentHint)
+        warnCommandArgumentHint(ctx, "gemini", command.name);
+      if (command.allowedTools?.length)
+        warnCommandAllowedTools(ctx, "gemini", command.name);
+      if (command.frontmatter && Object.keys(command.frontmatter).length > 0)
+        warnCommandFrontmatter(ctx, "gemini", command.name);
       files.push({
         path: `commands/${command.name}.toml`,
         content: geminiCommandToml({

packages/agent-plugin-sdk/src/harnesses/hooks.ts

@@ -90,6 +90,20 @@ function warnAsync(ctx: EmitContext | undefined, harness: HarnessId): void {
   });
 }
 
+/** Warn (once per hook) that a harness dropped the `powershell` command variant. */
+function warnPowershell(ctx: EmitContext | undefined, harness: HarnessId): void {
+  ctx?.warn({
+    type: "unsupported-option",
+    harness,
+    feature: "hooks",
+    option: "powershell",
+    items: ["powershell"],
+    details:
+      `${harness} hook entries have a single command slot with no ` +
+      "per-platform variant, so the `bash` command is used everywhere.",
+  });
+}
+
 /** Warn (once per hook) that a harness has no native form for this event. */
 function warnEvent(
   ctx: EmitContext | undefined,
@@ -131,6 +145,9 @@ export function buildMatcherHooks(
       warnEvent(ctx, harness, hook.event);
       continue;
     }
+    if (typeof hook.command !== "string" && hook.command.powershell) {
+      warnPowershell(ctx, harness);
+    }
     const inner: Record<string, unknown> = {
       type: "command",
       command: bashOf(hook.command),

packages/agent-plugin-sdk/src/harnesses/opencode.ts

@@ -13,6 +13,10 @@ import {
   emitContextFile,
   emitSkillDir,
   json,
+  warnCommandAllowedTools,
+  warnCommandArgumentHint,
+  warnSkillAllowedTools,
+  warnSkillDisableModelInvocation,
 } from "./shared.js";
 import { toOpenCodeEntry } from "./mcp.js";
 import { openCodePluginEntry } from "./tools.js";
@@ -84,6 +88,10 @@ export const opencode: Harness = {
         compatibility: "opencode",
         metadata: skill.metadata,
       });
+      if (skill.allowedTools?.length)
+        warnSkillAllowedTools(ctx, "opencode", skill.name);
+      if (skill.disableModelInvocation)
+        warnSkillDisableModelInvocation(ctx, "opencode", skill.name);
       files.push(...emitSkillDir(skill, frontmatter, "skills"));
     }
 
@@ -95,6 +103,10 @@ export const opencode: Harness = {
         description: command.description,
         model: command.harness?.opencode?.model,
       });
+      if (command.argumentHint)
+        warnCommandArgumentHint(ctx, "opencode", command.name);
+      if (command.allowedTools?.length)
+        warnCommandAllowedTools(ctx, "opencode", command.name);
       files.push(
         emitCommandFile(
           command.name,