fix(spec): rewrite skill.zod.ts's two @example blocks off the retired triggerPhrases

.changeset/skill-zod-examples-drop-retired-trigger-phrases.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+**Docs:** `skill.zod.ts`'s two `@example` blocks stop handing the author a retired key that throws on parse (#11026).
+
+Both TSDoc examples in `packages/spec/src/ai/skill.zod.ts` — the one over `SkillSchema` and the one over `defineSkill` — passed `triggerPhrases`, removed in `@objectstack/spec` 17.0.0 (#3896 audit close-out) and carried as a `retiredKey()` tombstone ~120 lines below the first of them. `defineSkill` calls `SkillSchema.parse()`, so both documented blocks **threw** when run: `invalid_type` at path `triggerPhrases`, expected `never`. A reader copying either block got a refusal on their first move.
+
+The blocks now demonstrate the tombstone's own prescription instead of contradicting it. That prescription is a **split**, not a rename — routing intent belongs in `triggerConditions` (an AND of context field/operator/value), natural-language intent in `description` / `instructions`, the strings actually put in front of the model — and the `defineSkill` block shows both halves with each named. `tools` is required with no default, so both blocks carry it. Each block also opens with its own `import { defineSkill } from '@objectstack/spec';`, matching the convention the marked SDK examples in `packages/client-react/src` already use, so the block is self-contained as a consumer would resolve it.
+
+The tombstone and every line of its guidance prose are **unchanged**, verbatim — they were always correct, and they are what the repaired examples now agree with.
+
+Prose only: no schema shape, no `.describe()` text, no runtime behaviour, no authorable-surface movement, and `check:generated` moves nothing (the generated reference page `content/docs/references/ai/skill.mdx` renders the tombstoned row as `[REMOVED]` and carries neither example). It is graded rather than skipped because the text ships to consumers: the rewritten blocks are present in the built `dist/skill.zod-*.d.ts`, which is what an editor surfaces on hover, and `@objectstack/spec`'s `files` list publishes `src/**/*.zod.ts` so the docblock also travels in the npm tarball as source.

packages/spec/src/ai/skill.zod.ts

@@ -247,13 +247,18 @@ export type SkillTriggerCondition = z.input<typeof SkillTriggerConditionSchema>;
  *
  * @example
  * ```ts
+ * import { defineSkill } from '@objectstack/spec';
+ *
  * const skill = defineSkill({
  * name: 'case_management',
  * label: 'Case Management',
  * description: 'Handles support case lifecycle',
- * instructions: 'Use these tools to create, update, and resolve support cases.',
+ * // Natural-language intent lives in the strings actually put in front of
+ * // the model. A skill is never activated by matching a phrase list.
+ * instructions:
+ * 'Use these tools to create, update, and resolve support cases. Reach for this '
+ * + 'skill when the user wants to open a ticket, chase an existing case, or close one out.',
  * tools: ['create_case', 'update_case', 'resolve_case', 'query_cases'],
- * triggerPhrases: ['create a case', 'open a ticket', 'resolve issue'],
  * });
  * ```
  */
@@ -432,14 +437,24 @@ export type SkillParsed = z.infer<typeof SkillSchema>;
  * Validates the config at creation time using Zod `.parse()`.
  *
  * @example
+ * Activation is a SPLIT, and this block shows both halves: programmatic
+ * routing in `triggerConditions`, natural-language intent in
+ * `description` / `instructions`.
+ *
  * ```ts
+ * import { defineSkill } from '@objectstack/spec';
+ *
  * const skill = defineSkill({
  * name: 'order_management',
  * label: 'Order Management',
  * description: 'Handles order lifecycle operations',
- * instructions: 'Use these tools to manage customer orders.',
+ * // Half one — natural language, read by the LLM.
+ * instructions:
+ * 'Use these tools to manage customer orders. Reach for this skill when the user '
+ * + 'wants to place an order, change one, or cancel one.',
  * tools: ['create_order', 'update_order', 'cancel_order'],
- * triggerPhrases: ['place an order', 'cancel my order'],
+ * // Half two — a programmatic AND of context field/operator/value,
+ * // evaluated by the cloud agent runtime.
  * triggerConditions: [
  * { field: 'objectName', operator: 'eq', value: 'order' },
  * ],