feat(ai): Agent→Skill→Tool three-tier metadata protocol

[Copilot]

Current agent.zod.ts treats tools as inline references only. Industry standard (Salesforce Agentforce, Copilot Studio, ServiceNow) uses Agent→Skill→Tool: Tool as first-class metadata, Skill as reusable ability group, Agent as lightweight config referencing skills.

New protocols

• src/ai/tool.zod.ts — ToolSchema with JSON Schema parameters/outputSchema, category enum, objectName binding, requiresConfirmation, permissions, builtIn flag. defineTool() factory.
• src/ai/skill.zod.ts — SkillSchema aggregating tool references by domain. Supports instructions (injected into system prompt), triggerPhrases (intent matching), triggerConditions (programmatic activation via field/operator/value). defineSkill() factory.

Agent refactoring

• Added skills: string[] as primary capability model
• Existing tools: AIToolSchema[] retained as backward-compatible fallback
• Added permissions: string[] for access control

Metadata registry

• tool and skill added to MetadataTypeSchema enum and DEFAULT_METADATA_TYPE_REGISTRY
• Load order: tool (85) → skill (88) → agent (90)
• File patterns: **/*.tool.{ts,yml}, **/*.skill.{ts,yml}

Usage

const tool = defineTool({
  name: 'create_case',
  label: 'Create Case',
  description: 'Creates a support case',
  category: 'action',
  parameters: { type: 'object', properties: { subject: { type: 'string' } }, required: ['subject'] },
  objectName: 'support_case',
  requiresConfirmation: true,
});

const skill = defineSkill({
  name: 'case_management',
  label: 'Case Management',
  instructions: 'Use these tools to manage support cases.',
  tools: ['create_case', 'update_case', 'resolve_case'],
  triggerPhrases: ['open a ticket', 'create a case'],
});

const agent = defineAgent({
  name: 'support_agent',
  label: 'Support Agent',
  role: 'Support Specialist',
  instructions: 'Help customers resolve issues.',
  skills: ['case_management', 'knowledge_search'],
});

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Mar 31, 2026 9:35am
spec	Ready	Preview, Comment	Mar 31, 2026 9:35am

[Copilot]

Pull request overview

Introduces first-class Tool and Skill metadata protocols in packages/spec, and refactors the existing AI Agent metadata to primarily reference skills (Agent → Skill → Tool), while keeping legacy inline tools for backward compatibility.

Changes:

• Added new AI metadata schemas + factories: ToolSchema/defineTool() and SkillSchema/defineSkill(), with unit tests.
• Updated AgentSchema to support skills: string[] (primary) and permissions: string[], retaining legacy tools.
• Registered new metadata kinds (tool, skill) in the kernel metadata type registry and exported them from @objectstack/spec and @objectstack/spec/ai.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/spec/src/kernel/metadata-plugin.zod.ts	Adds tool/skill to MetadataTypeSchema and DEFAULT_METADATA_TYPE_REGISTRY with load ordering.
packages/spec/src/kernel/metadata-plugin.test.ts	Updates tests to include the new metadata types and domain assertions.
packages/spec/src/index.ts	Re-exports defineTool, defineSkill, and Tool/Skill types at the root package entrypoint.
packages/spec/src/ai/tool.zod.ts	Introduces ToolSchema + ToolCategorySchema and defineTool() factory.
packages/spec/src/ai/tool.test.ts	Adds unit tests for tool schema validation and defaults.
packages/spec/src/ai/skill.zod.ts	Introduces SkillSchema + trigger condition schema and defineSkill() factory.
packages/spec/src/ai/skill.test.ts	Adds unit tests for skill schema validation and defaults.
packages/spec/src/ai/index.ts	Re-exports tool/skill schemas from the AI subpath.
packages/spec/src/ai/agent.zod.ts	Adds skills and permissions fields; documents skill-based architecture while keeping legacy tools.
packages/spec/src/ai/agent.test.ts	Adds coverage for agents using skills, hybrid skills+tools, and permissions.
packages/spec/CHANGELOG.md	Documents the new Agent/Skill/Tool protocol and exports.

[Copilot]

SkillSchema.tools is a list of tool name references, but it currently allows any string. Since ToolSchema.name enforces snake_case, this should validate the same pattern (or reuse a shared schema) so invalid references are caught at parse-time rather than failing later during tool resolution.

[Copilot]

AgentSchema.skills is intended to reference SkillSchema.name values (snake_case), but it currently allows any string. Validating the same snake_case pattern here would prevent invalid skill references from passing schema validation and failing later at runtime.

Suggested change

	skills: z.array(z.string()).optional().describe('Skill names to attach (Agent→Skill→Tool architecture)'),
	skills: z
	.array(z.string().regex(/^[a-z_][a-z0-9_]*$/))
	.optional()
	.describe('Skill names to attach (Agent→Skill→Tool architecture)'),

[hotlong]

@copilot fix all

[Copilot]

@copilot fix all

Fixed both review comments in 3163230:

• SkillSchema.tools now enforces snake_case (/^[a-z_][a-z0-9_]*$/) on tool name references
• AgentSchema.skills now enforces the same snake_case pattern on skill name references
• Added tests for both validations — all 6773 tests pass.