refactor: move agent tool bundles into skills metadata

Author: hotlong

packages/services/service-ai/src/__tests__/chatbot-features.test.ts

@@ -16,6 +16,7 @@ import { ToolRegistry } from '../tools/tool-registry.js';
 import { registerDataTools, DATA_TOOL_DEFINITIONS } from '../tools/data-tools.js';
 import type { DataToolContext } from '../tools/data-tools.js';
 import { AgentRuntime } from '../agent-runtime.js';
+import { SkillRegistry } from '../skill-registry.js';
 import type { AgentChatContext } from '../agent-runtime.js';
 import { buildAgentRoutes } from '../routes/agent-routes.js';
 import { DATA_CHAT_AGENT } from '../agents/data-chat-agent.js';
@@ -603,7 +604,8 @@ describe('AgentRuntime', () => {
 
   beforeEach(() => {
     metadataService = createMockMetadataService();
-    runtime = new AgentRuntime(metadataService);
+    const skillRegistry = new SkillRegistry(metadataService);
+    runtime = new AgentRuntime(metadataService, skillRegistry);
   });
 
   describe('loadAgent', () => {
@@ -663,16 +665,17 @@ describe('AgentRuntime', () => {
       expect(options.maxTokens).toBe(4096);
     });
 
-    it('should resolve agent tool references against available tools', () => {
+    it('should resolve skill tool references against available tools', async () => {
       const availableTools: AIToolDefinition[] = [
         { name: 'list_objects', description: 'List objects', parameters: {} },
         { name: 'query_records', description: 'Query records', parameters: {} },
-        { name: 'unrelated_tool', description: 'Not in agent', parameters: {} },
+        { name: 'unrelated_tool', description: 'Not in any skill', parameters: {} },
       ];
 
-      const options = runtime.buildRequestOptions(DATA_CHAT_AGENT, availableTools);
+      // DATA_CHAT_AGENT now references the data_explorer skill which carries the tools.
+      const { DATA_EXPLORER_SKILL } = await import('../skills/data-explorer-skill.js');
+      const options = runtime.buildRequestOptions(DATA_CHAT_AGENT, availableTools, [DATA_EXPLORER_SKILL]);
 
-      // Only tools declared in agent.tools that exist in available should be resolved
       const resolvedNames = options.tools?.map(t => t.name) ?? [];
       expect(resolvedNames).toContain('list_objects');
       expect(resolvedNames).toContain('query_records');
@@ -1036,14 +1039,9 @@ describe('DATA_CHAT_AGENT', () => {
     expect(DATA_CHAT_AGENT.visibility).toBe('global');
   });
 
-  it('should reference all 5 data tools', () => {
-    expect(DATA_CHAT_AGENT.tools).toHaveLength(5);
-    const toolNames = DATA_CHAT_AGENT.tools!.map(t => t.name);
-    expect(toolNames).toContain('list_objects');
-    expect(toolNames).toContain('describe_object');
-    expect(toolNames).toContain('query_records');
-    expect(toolNames).toContain('get_record');
-    expect(toolNames).toContain('aggregate_data');
+  it('should reference the data_explorer skill (capability bundle moved to skill metadata)', () => {
+    expect(DATA_CHAT_AGENT.tools ?? []).toHaveLength(0);
+    expect(DATA_CHAT_AGENT.skills).toEqual(['data_explorer']);
   });
 
   it('should have guardrails configured', () => {
@@ -1071,23 +1069,14 @@ describe('METADATA_ASSISTANT_AGENT', () => {
     expect(METADATA_ASSISTANT_AGENT.visibility).toBe('global');
   });
 
-  it('should reference all 6 metadata tools', () => {
-    expect(METADATA_ASSISTANT_AGENT.tools).toHaveLength(6);
-    const toolNames = METADATA_ASSISTANT_AGENT.tools!.map(t => t.name);
-    expect(toolNames).toContain('create_object');
-    expect(toolNames).toContain('add_field');
-    expect(toolNames).toContain('modify_field');
-    expect(toolNames).toContain('delete_field');
-    expect(toolNames).toContain('list_objects');
-    expect(toolNames).toContain('describe_object');
+  it('should reference the metadata_authoring skill (capability bundle moved to skill metadata)', () => {
+    expect(METADATA_ASSISTANT_AGENT.tools ?? []).toHaveLength(0);
+    expect(METADATA_ASSISTANT_AGENT.skills).toEqual(['metadata_authoring']);
   });
 
-  it('should use action type for mutation tools and query type for read tools', () => {
-    const tools = METADATA_ASSISTANT_AGENT.tools!;
-    const actionTools = tools.filter(t => t.type === 'action');
-    const queryTools = tools.filter(t => t.type === 'query');
-    expect(actionTools).toHaveLength(4); // create, add, modify, delete
-    expect(queryTools).toHaveLength(2); // list, describe
+  it('should keep the schema-architect persona in instructions', () => {
+    const instructions = METADATA_ASSISTANT_AGENT.instructions;
+    expect(instructions).toMatch(/architect/i);
   });
 
   it('should have guardrails configured', () => {
@@ -1107,10 +1096,8 @@ describe('METADATA_ASSISTANT_AGENT', () => {
     expect(METADATA_ASSISTANT_AGENT.planning!.allowReplan).toBe(true);
   });
 
-  it('should have instructions mentioning metadata management capabilities', () => {
+  it('should have instructions mentioning the architect persona', () => {
     const instructions = METADATA_ASSISTANT_AGENT.instructions;
-    expect(instructions).toContain('snake_case');
-    expect(instructions).toContain('list_objects');
-    expect(instructions).toContain('describe_object');
+    expect(instructions).toMatch(/architect|metadata/i);
   });
 });

packages/services/service-ai/src/agents/data-chat-agent.ts

@@ -3,11 +3,20 @@
 import type { Agent } from '@objectstack/spec/ai';
 
 /**
- * Built-in `data_chat` agent definition.
+ * Built-in `data_chat` agent — a thin **persona** record.
  *
- * This agent powers the Airtable-style data conversation Chatbot.
- * It is registered automatically by the AI service plugin when a
- * data engine is available.
+ * Following the platform's metadata-driven philosophy, this agent no
+ * longer hardcodes the tools it can call. The capability bundle lives
+ * on the `data_explorer` *skill* (see `../skills/data-explorer-skill.ts`).
+ * The agent record is now just:
+ *   - identity (name / label / role)
+ *   - persona (system prompt)
+ *   - model + safety config
+ *   - skills attached → `skills: ['data_explorer']`
+ *
+ * To grant data-exploration powers to a different agent, just add
+ * `data_explorer` to its `skills[]`. To revoke globally, set the
+ * skill's `active: false` in metadata.
  *
  * @example
  * ```
@@ -24,21 +33,7 @@ export const DATA_CHAT_AGENT: Agent = {
   role: 'Business Data Analyst',
   instructions: `You are a helpful data assistant that helps users explore and understand their business data through natural language.
 
-Capabilities:
-- List available data objects (tables) and their schemas
-- Query records with filters, sorting, and pagination
-- Look up individual records by ID
-- Perform aggregations and statistical analysis (count, sum, avg, min, max)
-
-Guidelines:
-1. Always use the describe_object tool first to understand a table's structure before querying it.
-2. Respect the user's current context — if they are viewing a specific object or record, use that as the default scope.
-3. When presenting data, format it in a clear and readable way using markdown tables or bullet lists.
-4. For large result sets, summarize the data and mention the total count.
-5. When performing aggregations, explain the results in plain language.
-6. If a query returns no results, suggest possible reasons and alternative queries.
-7. Never expose internal IDs unless the user explicitly asks for them.
-8. Always answer in the same language the user is using.`,
+Always answer in the same language the user is using. Detailed tool-usage guidance is supplied by the skills attached to this agent.`,
 
   model: {
     provider: 'openai',
@@ -47,13 +42,8 @@ Guidelines:
     maxTokens: 4096,
   },
 
-  tools: [
-    { type: 'query', name: 'list_objects', description: 'List all available data objects' },
-    { type: 'query', name: 'describe_object', description: 'Get schema/fields of a data object' },
-    { type: 'query', name: 'query_records', description: 'Query records with filters and pagination' },
-    { type: 'query', name: 'get_record', description: 'Get a single record by ID' },
-    { type: 'query', name: 'aggregate_data', description: 'Aggregate/statistics on data' },
-  ],
+  // Capability bundle lives on the skill; the agent only references it.
+  skills: ['data_explorer'],
 
   active: true,
   visibility: 'global',
@@ -77,3 +67,4 @@ Guidelines:
     },
   },
 };
+

packages/services/service-ai/src/agents/metadata-assistant-agent.ts

@@ -3,14 +3,16 @@
 import type { Agent } from '@objectstack/spec/ai';
 
 /**
- * Built-in `metadata_assistant` agent definition.
+ * Built-in `metadata_assistant` agent — a thin **persona** record.
  *
- * This agent powers AI-driven metadata management — users can create objects,
- * add/modify/delete fields, and inspect schema definitions through natural
- * language conversation.
+ * Capability bundle is no longer hardcoded here; it lives on the
+ * `metadata_authoring` *skill* (see
+ * `../skills/metadata-authoring-skill.ts`). Studio's Universal
+ * Assistant pins this agent via `?agent=metadata_assistant` because
+ * Studio is a metadata-authoring host.
  *
- * It is registered automatically by the AI service plugin alongside the
- * `data_chat` agent when the metadata service is available.
+ * To extend this agent (e.g. give it data-exploration too), just add
+ * the skill name: `skills: ['metadata_authoring', 'data_explorer']`.
  *
  * @example
  * ```
@@ -27,25 +29,7 @@ export const METADATA_ASSISTANT_AGENT: Agent = {
   role: 'Schema Architect',
   instructions: `You are an expert metadata architect that helps users design and manage their data models through natural language.
 
-Capabilities:
-- Create new data objects (tables) with fields
-- Add fields (columns) to existing objects
-- Modify field properties (label, type, required, default value)
-- Delete fields from objects
-- List all registered metadata objects and their schemas
-- Describe the full schema of a specific object
-
-Guidelines:
-1. Before creating a new object, use list_objects to check if a similar one already exists.
-2. Before modifying or deleting fields, use describe_object to understand the current schema.
-3. Always use snake_case for object names and field names (e.g. project_task, due_date).
-4. Suggest meaningful field types based on the user's description (e.g. "deadline" → date, "active" → boolean).
-5. When creating objects, propose a reasonable set of initial fields based on the entity type.
-6. Explain what changes you are about to make before executing them.
-7. After making changes, confirm the result by describing the updated schema.
-8. For destructive operations (deleting fields), always warn the user about potential data loss.
-9. Always answer in the same language the user is using.
-10. If the user's request is ambiguous, ask clarifying questions before proceeding.`,
+Always answer in the same language the user is using. If the user's request is ambiguous, ask clarifying questions before proceeding. Detailed tool-usage guidance is supplied by the skills attached to this agent.`,
 
   model: {
     provider: 'openai',
@@ -54,14 +38,8 @@ Guidelines:
     maxTokens: 4096,
   },
 
-  tools: [
-    { type: 'action', name: 'create_object', description: 'Create a new data object (table)' },
-    { type: 'action', name: 'add_field', description: 'Add a field to an existing object' },
-    { type: 'action', name: 'modify_field', description: 'Modify an existing field definition' },
-    { type: 'action', name: 'delete_field', description: 'Delete a field from an object' },
-    { type: 'query', name: 'list_objects', description: 'List all data objects' },
-    { type: 'query', name: 'describe_object', description: 'Describe an object schema' },
-  ],
+  // Capability bundle lives on the skill; the agent only references it.
+  skills: ['metadata_authoring'],
 
   active: true,
   visibility: 'global',
@@ -85,3 +63,4 @@ Guidelines:
     },
   },
 };
+

packages/services/service-ai/src/plugin.ts

@@ -15,6 +15,7 @@ import { registerMetadataTools } from './tools/metadata-tools.js';
 import { AgentRuntime } from './agent-runtime.js';
 import { SkillRegistry } from './skill-registry.js';
 import { DATA_CHAT_AGENT, METADATA_ASSISTANT_AGENT } from './agents/index.js';
+import { DATA_EXPLORER_SKILL, METADATA_AUTHORING_SKILL } from './skills/index.js';
 import { VercelLLMAdapter } from './adapters/vercel-adapter.js';
 import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
 
@@ -311,6 +312,25 @@ export class AIServicePlugin implements Plugin {
           } catch (err) {
             ctx.logger.warn('[AI] Failed to register data_chat agent', err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
           }
+
+          // Register the built-in data_explorer skill (capability bundle for data_chat)
+          try {
+            const skillExists =
+              typeof metadataService.exists === 'function'
+                ? await withTimeout(metadataService.exists('skill', DATA_EXPLORER_SKILL.name))
+                : false;
+
+            if (skillExists === null) {
+              ctx.logger.warn('[AI] Metadata service timed out checking data_explorer skill, skipping');
+            } else if (!skillExists) {
+              await withTimeout(metadataService.register('skill', DATA_EXPLORER_SKILL.name, DATA_EXPLORER_SKILL));
+              ctx.logger.info('[AI] data_explorer skill registered');
+            } else {
+              ctx.logger.debug('[AI] data_explorer skill already exists, skipping auto-registration');
+            }
+          } catch (err) {
+            ctx.logger.warn('[AI] Failed to register data_explorer skill', err instanceof Error ? { error: err.message } : { error: String(err) });
+          }
         }
       }
     } catch {
@@ -367,6 +387,25 @@ export class AIServicePlugin implements Plugin {
         } catch (err) {
           ctx.logger.warn('[AI] Failed to register metadata_assistant agent', err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
         }
+
+        // Register the built-in metadata_authoring skill (capability bundle for metadata_assistant)
+        try {
+          const skillExists =
+            typeof metadataService.exists === 'function'
+              ? await withTimeout(metadataService.exists('skill', METADATA_AUTHORING_SKILL.name))
+              : false;
+
+          if (skillExists === null) {
+            ctx.logger.warn('[AI] Metadata service timed out checking metadata_authoring skill, skipping');
+          } else if (!skillExists) {
+            await withTimeout(metadataService.register('skill', METADATA_AUTHORING_SKILL.name, METADATA_AUTHORING_SKILL));
+            ctx.logger.info('[AI] metadata_authoring skill registered');
+          } else {
+            ctx.logger.debug('[AI] metadata_authoring skill already exists, skipping auto-registration');
+          }
+        } catch (err) {
+          ctx.logger.warn('[AI] Failed to register metadata_authoring skill', err instanceof Error ? { error: err.message } : { error: String(err) });
+        }
       } catch (err) {
         ctx.logger.debug('[AI] Failed to register metadata tools', err instanceof Error ? err : undefined);
       }

packages/services/service-ai/src/skills/data-explorer-skill.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Skill } from '@objectstack/spec/ai';
+
+/**
+ * Built-in `data_explorer` skill — the read-only data-Q&A capability
+ * bundle that the `data_chat` agent (and any other agent that wants
+ * data-exploration powers) attaches to its `skills[]`.
+ *
+ * Following the platform's metadata-driven philosophy, the agent
+ * itself no longer hardcodes which tools it can call; instead it
+ * names this skill and the SkillRegistry resolves the tool list at
+ * request time. Disabling this skill via the metadata service
+ * disables data exploration for every agent that references it,
+ * without code changes.
+ */
+export const DATA_EXPLORER_SKILL: Skill = {
+  name: 'data_explorer',
+  label: 'Data Explorer',
+  description: 'Read-only Q&A over the user\'s business data — schema discovery, filtered queries, lookups, and aggregations.',
+  instructions: `You can explore the user's business data through these tools.
+
+Capabilities:
+- List available data objects (tables) and their schemas
+- Query records with filters, sorting, and pagination
+- Look up individual records by ID
+- Perform aggregations and statistical analysis (count, sum, avg, min, max)
+
+Guidelines:
+1. Always use the describe_object tool first to understand a table's structure before querying it.
+2. Respect the user's current context — if they are viewing a specific object or record, use that as the default scope.
+3. When presenting data, format it in a clear and readable way using markdown tables or bullet lists.
+4. For large result sets, summarize the data and mention the total count.
+5. When performing aggregations, explain the results in plain language.
+6. If a query returns no results, suggest possible reasons and alternative queries.
+7. Never expose internal IDs unless the user explicitly asks for them.
+8. Always answer in the same language the user is using.`,
+  tools: [
+    'list_objects',
+    'describe_object',
+    'query_records',
+    'get_record',
+    'aggregate_data',
+  ],
+  triggerPhrases: [
+    'show me',
+    'list',
+    'how many',
+    'count',
+    'find records',
+    'query',
+    'aggregate',
+    'sum',
+    'average',
+  ],
+  active: true,
+};

packages/services/service-ai/src/skills/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { DATA_EXPLORER_SKILL } from './data-explorer-skill.js';
+export { METADATA_AUTHORING_SKILL } from './metadata-authoring-skill.js';