skill.mdx

title	Skill
description	Skill protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Skill Trigger Condition Schema

Defines programmatic conditions under which a skill becomes active.

Allows context-aware activation based on object type, user role, etc.

**Source:** `packages/spec/src/ai/skill.zod.ts`

TypeScript Usage

import { Skill, SkillTriggerCondition } from '@objectstack/spec/ai';
import type { Skill, SkillTriggerCondition } from '@objectstack/spec/ai';

// Validate data
const result = Skill.parse(data);

---

Skill

Properties

Property	Type	Required	Description
name	string	✅	Skill unique identifier (snake_case)
label	string	✅	Skill display name
description	string	optional	Skill description
surface	Enum<'ask' | 'build' | 'both'>	✅	Agent surface this skill binds to ('ask' | 'build' | 'both') — ADR-0063 §3
instructions	string	optional	LLM instructions when skill is active
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
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).
_lockReason	string	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	Enum<'artifact' | 'package' | 'env-forced'>	optional	Layer that set _lock (artifact | package | env-forced).
_provenance	Enum<'package' | 'org' | 'env-forced'>	optional	Origin of the item (package | org | env-forced).
_packageId	string	optional	Owning package machine id.
_packageVersion	string	optional	Owning package version.
_lockDocsUrl	string	optional	Optional documentation link surfaced next to _lockReason.

---

SkillTriggerCondition

Properties

Property	Type	Required	Description
field	string	✅	Context field to evaluate
operator	Enum<'eq' | 'neq' | 'in' | 'not_in' | 'contains'>	✅	Comparison operator
value	string | string[]	✅	Expected value or values

---