feat(spec)!: remove SkillSchema.permissions — it never gated anything (#3686)

Owner decision on the enforce-or-prune call: prune.

skill.permissions was declared, surfaced in the Studio form under an "Access —
Required permissions to use this skill" section, and echoed by the objectui
preview — but no runtime read it. The cloud SkillRegistry selects skills by
active/triggerConditions/tools only. A security-shaped field that enforces
nothing invites an author (or an AI) to believe a skill is gated when it is
not — same disposition as agent `visibility` (#1901) and PolicySchema (#2387).

Removed: the schema property; the form's whole Access section (it existed only
for this field); its generated i18n keys (surgically, not via a full extract
rerun, which would drag in unrelated drift); the liveness-ledger entry + count
table row; and the `permissions` line from the objectstack-ai skill doc — both
its prop table (replaced by a migration note) and its os:check TS block, which
compiles against the spec and would otherwise fail check:skill-examples.

Added a regression test pinning that an authored `permissions` key is stripped
(SkillSchema is non-strict, so it degrades silently rather than breaking boot).

Verified: 6688 spec tests; check:liveness / check:docs / check:api-surface /
check:skill-docs / check:skill-examples all green.

Refs #3686, #1878.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/prune-skill-permissions.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: remove `SkillSchema.permissions` — it never gated anything (#3686)
+
+Owner decision on the enforce-or-prune call filed in #3686: **prune**.
+
+`skill.permissions` was declared, surfaced in the Studio authoring form under a
+section labelled *"Access — Required permissions to use this skill"*, and echoed
+by the objectui preview — but **no runtime ever read it**. The cloud
+`SkillRegistry` selects skills by `active` / `triggerConditions` / `tools` only.
+A security-shaped field that enforces nothing is worse than no field: it invites
+an author (or an AI) to believe a skill is gated when it is not. Same disposition
+as agent `visibility` (#1901) and the `PolicySchema` tree (#2387).
+
+Removed: the schema property, the form's whole `Access` section (it existed only
+for this field), its generated i18n keys, the liveness-ledger entry, and the
+`permissions` line from the objectstack-ai skill doc's `os:check` example. The
+objectui preview's "Required Permissions" panel is removed in the companion
+objectui change.
+
+**Migration** — gate access where it is actually enforced:
+- **Agent level** — `access` / `permissions` on `defineAgent` ARE enforced at the
+  chat route (403 for a caller missing any of them, #1884). Bind the restricted
+  skill only to a restricted agent.
+- **Action level** — gate the underlying actions the skill's tools invoke via
+  permission sets (ADR-0066).
+
+`SkillSchema` is non-strict, so an existing `permissions:` key is silently
+stripped on parse rather than rejected — no boot break, but it stops appearing
+anywhere.

content/docs/references/ai/skill.mdx

@@ -41,7 +41,6 @@ const result = Skill.parse(data);
 | **tools** | `string[]` | ✅ | Tool names belonging to this skill (supports trailing wildcard, e.g. `action_*`) |
 | **triggerPhrases** | `string[]` | optional | Phrases that activate this skill |
 | **triggerConditions** | `{ field: string; operator: Enum<'eq' \| 'neq' \| 'in' \| 'not_in' \| 'contains'>; value: string \| string[] }[]` | optional | Programmatic activation conditions |
-| **permissions** | `string[]` | optional | Required permissions or roles |
 | **active** | `boolean` | ✅ | Whether the skill is enabled |
 | **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | optional | Package author protection block — lock policy for this skill. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -1717,10 +1717,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       triggers: {
         label: "Triggers",
         description: "When this skill should activate."
-      },
-      access: {
-        label: "Access",
-        description: "Required permissions to use this skill."
       }
     },
     fields: {
@@ -1755,10 +1751,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       triggerConditions: {
         label: "Trigger Conditions",
         helpText: "Programmatic conditions (e.g., objectName == \"case\")"
-      },
-      permissions: {
-        label: "Permissions",
-        helpText: "Required permissions to use this skill"
       }
     }
   }

packages/spec/liveness/README.md

@@ -232,7 +232,7 @@ EOF
 | position | 4 | – | – | – | (role's ADR-0090 successor) fully live |
 | agent | 13 | 5 | 1 | – | dead `tenantId` + `planning.strategy`/`allowReplan` REMOVED (#2377) — only `planning.maxIterations` live; autonomy tier experimental; `knowledge` CORRECTED to dead 2026-07 — `search_knowledge` takes `sourceIds` from the LLM's tool-call args, never from the agent record (#1878 §3 recheck) |
 | tool | 9 | 1 | 1 | – | `permissions` dead — tool invocation not permission-gated by it |
-| skill | 9 | – | 1 | – | `permissions` CORRECTED to dead 2026-07 — the cloud SkillRegistry reads only `active`/`triggerConditions`/`tools`; mirrors the identical `tool.permissions` entry (#1878 §3 recheck) |
+| skill | 9 | – | – | – | `permissions` REMOVED 2026-07 — never permission-gated anything (the cloud SkillRegistry reads only `active`/`triggerConditions`/`tools`); owner call was prune, not enforce. Gate at the agent (`access`/`permissions`, #1884) or on the tools' underlying actions |
 | dataset | 19 | – | 0 | – | `measures.certified` (declared-but-unenforced governance flag) REMOVED in 16.0 (#2377) |
 | page | 16 | – | – | 1 | fully live + one planned |
 | view | 70 | 0 | 5 | – | list/form drilled via `children` (#2998 Track B); dead = list.{responsive,performance} + form.{data,defaultSort,aria}, all but aria authorWarn'd; form.{buttons,defaults} now live — objectui ObjectForm folds them onto its flat props (framework#1894 / #2998); audit-era DEAD lines superseded by re-verification (submitBehavior, sharing.lockedBy, list ViewData providers, and the ADR-0021 chart shape — all live now); level-2 dead residue (userActions.buttons, addRecord.mode/formView, tabs[].order) noted on parents — one drill level only |

packages/spec/liveness/skill.json

@@ -45,13 +45,6 @@
       "status": "live",
       "evidence": "objectui: packages/app-shell/src/views/metadata-admin/previews/SkillPreview.tsx:44",
       "note": "LIVE via objectui metadata-admin authoring UI — the 2026-06 audit missed objectui; verified by reading the file."
-    },
-    "permissions": {
-      "status": "dead",
-      "evidence": "skill.form.ts + objectui SkillPreview.tsx:48 (both authoring-side echo only); no gate in the cloud SkillRegistry",
-      "authorWarn": true,
-      "authorHint": "Skill invocation is NOT permission-gated by this list — the registry reads only `active`/`triggerConditions`/`tools`. Agent-level `access`/`permissions` ARE enforced (#1884), so gate at the agent, or gate the underlying tools' actions via permission sets (ADR-0066).",
-      "note": "CORRECTED 2026-07 (#1878 §3 recheck): was marked live on the evidence of the metadata-admin PREVIEW renderer — an echo of what the author typed, not runtime consumption. Mirrors the identical `tool.permissions` entry. Cloud documents the intent ('Layer permissions via Skill.permissions independent of the agent's permissions', service-ai-studio/src/skills/metadata-authoring-skill.ts:15) without implementing it — enforce-or-prune tracked separately."
     }
   }
 }

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

@@ -40,14 +40,5 @@ export const skillForm = defineForm({
         { field: 'triggerConditions', type: 'repeater', helpText: 'Programmatic conditions (e.g., objectName == "case")' },
       ],
     },
-    {
-      label: 'Access',
-      description: 'Required permissions to use this skill.',
-      collapsible: true,
-      collapsed: true,
-      fields: [
-        { field: 'permissions', widget: 'string-tags', helpText: 'Required permissions to use this skill' },
-      ],
-    },
   ],
 });

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

@@ -64,7 +64,6 @@ describe('SkillSchema', () => {
         { field: 'objectName', operator: 'eq' as const, value: 'order' },
         { field: 'userRole', operator: 'in' as const, value: ['sales', 'support'] },
       ],
-      permissions: ['order.manage', 'order.view'],
       active: true,
     };
 
@@ -73,7 +72,20 @@ describe('SkillSchema', () => {
     expect(result.tools).toHaveLength(4);
     expect(result.triggerPhrases).toHaveLength(3);
     expect(result.triggerConditions).toHaveLength(2);
-    expect(result.permissions).toEqual(['order.manage', 'order.view']);
+  });
+
+  it('drops a `permissions` key — skill invocation was never permission-gated (pruned)', () => {
+    const parsed = SkillSchema.parse({
+      name: 'order_management',
+      label: 'Order Management',
+      instructions: 'x',
+      tools: ['create_order'],
+      // Authored against the retired key: the schema is non-strict, so it is
+      // stripped rather than rejected. Gate at the AGENT (`access`/`permissions`,
+      // enforced #1884) or on the underlying tools' actions instead.
+      permissions: ['order.manage'],
+    } as Record<string, unknown>);
+    expect('permissions' in parsed).toBe(false);
   });
 
   it('should enforce snake_case for skill name', () => {

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

@@ -117,9 +117,6 @@ export const SkillSchema = lazySchema(() => z.object({
    */
   triggerConditions: z.array(SkillTriggerConditionSchema).optional().describe('Programmatic activation conditions'),
 
-  /** Permission profiles/roles required to use this skill */
-  permissions: z.array(z.string()).optional().describe('Required permissions or roles'),
-
   /** Whether the skill is enabled */
   active: z.boolean().default(true).describe('Whether the skill is enabled'),
   /**

skills/objectstack-ai/SKILL.md

@@ -238,9 +238,15 @@ trigger conditions.
 | `instructions` | LLM prompt guidance specific to this skill's context |
 | `triggerPhrases` | Natural language phrases that activate the skill |
 | `triggerConditions` | Programmatic activation rules |
-| `permissions` | Required permission profiles/roles |
 | `active` | Is the skill enabled (default: `true`) |
 
+> A skill has **no `permissions` key** — it was removed in 16.x. Skill invocation
+> was never gated by it (the registry reads only `active` / `triggerConditions` /
+> `tools`), and a security-shaped field that enforces nothing is worse than no
+> field at all. Gate access at the **agent** instead — `access` / `permissions` on
+> `defineAgent` are enforced at the chat route — or on the underlying actions the
+> skill's tools call (permission sets, ADR-0066).
+
 ### Skill Example
 
 <!-- os:check -->
@@ -272,7 +278,6 @@ export default defineSkill({
   triggerConditions: [
     { field: 'objectName', operator: 'eq', value: 'support_case' },
   ],
-  permissions: ['support_agent', 'support_admin'],
   active: true,
 });
 ```