feat: skills: define skills interface (#251)

Author: kalenkevich

core/src/common.ts

@@ -225,6 +225,8 @@ export {zodObjectToSchema} from './utils/simple_zod_to_json.js';
 export {GoogleLLMVariant} from './utils/variant_utils.js';
 export {version} from './version.js';
 
+export type {Frontmatter, Resources, Script, Skill} from './skills/skill.js';
+
 export * from './artifacts/base_artifact_service.js';
 export * from './memory/base_memory_service.js';
 export * from './sessions/base_session_service.js';

core/src/skills/prompt.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Frontmatter, Skill} from './skill.js';
+
+function escapeHtml(unsafe: string): string {
+  return unsafe
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Formats available skills into a standard XML string.
+ *
+ * @param skills A list of skill frontmatter or full skill objects.
+ * @returns XML string with <available_skills> block.
+ */
+export function formatSkillsAsXml(skills: Array<Skill | Frontmatter>): string {
+  if (!skills || skills.length === 0) {
+    return '<available_skills>\n</available_skills>';
+  }
+
+  const lines = ['<available_skills>'];
+
+  for (const item of skills) {
+    const frontmatter =
+      'frontmatter' in item ? (item.frontmatter as Frontmatter) : item;
+
+    lines.push('  <skill>');
+    lines.push(`    <name>${escapeHtml(frontmatter.name)}</name>`);
+    lines.push(
+      `    <description>${escapeHtml(frontmatter.description)}</description>`,
+    );
+    lines.push('  </skill>');
+  }
+
+  lines.push('</available_skills>');
+
+  return lines.join('\n');
+}

core/src/skills/skill.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {z} from 'zod';
+
+export const SNAKE_OR_KEBAB_NAME_PATTERN =
+  /^([a-z0-9]+(-[a-z0-9]+)*|[a-z0-9]+(_[a-z0-9]+)*)$/;
+
+/**
+ * Schema and Type for Skill Frontmatter metadata.
+ */
+export const FrontmatterSchema = z.preprocess(
+  (data) => {
+    if (typeof data === 'object' && data !== null) {
+      const obj = data as Record<string, unknown>;
+      if ('allowed-tools' in obj && !('allowedTools' in obj)) {
+        return {
+          ...obj,
+          allowedTools: obj['allowed-tools'],
+        };
+      }
+    }
+    return data;
+  },
+  z
+    .object({
+      name: z
+        .string()
+        .regex(SNAKE_OR_KEBAB_NAME_PATTERN, {
+          message:
+            'name must be lowercase kebab-case (a-z, 0-9, hyphens) or snake_case (a-z, 0-9, underscores), with no leading, trailing, or consecutive delimiters. Mixing hyphens and underscores is not allowed.',
+        })
+        .max(64),
+      description: z.string().min(1).max(1024),
+      license: z.string().optional(),
+      compatibility: z.string().max(500).optional(),
+      'allowed-tools': z.string().optional(),
+      metadata: z
+        .record(z.string(), z.any())
+        .default({})
+        .refine(
+          (data) => {
+            if ('adk_additional_tools' in data) {
+              return (
+                Array.isArray(data.adk_additional_tools) &&
+                data.adk_additional_tools.every(
+                  (item) => typeof item === 'string',
+                )
+              );
+            }
+            return true;
+          },
+          {
+            message: 'adk_additional_tools must be a list of strings',
+          },
+        ),
+    })
+    .loose(),
+);
+
+export interface Frontmatter {
+  name: string;
+  description: string;
+  license?: string;
+  compatibility?: string;
+  allowedTools?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Wrapper for script content.
+ */
+export interface Script {
+  src: string;
+}
+
+/**
+ * L3 skill content: additional instructions, assets, and scripts.
+ */
+export interface Resources {
+  references?: Record<string, string | Buffer>;
+  assets?: Record<string, string | Buffer>;
+  scripts?: Record<string, Script>;
+}
+
+/**
+ * Complete skill representation including frontmatter, instructions, and resources.
+ */
+export interface Skill {
+  frontmatter: Frontmatter;
+  instructions: string;
+  resources?: Resources;
+}

core/test/skills/prompt_test.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {describe, expect, it} from 'vitest';
+import {formatSkillsAsXml} from '../../src/skills/prompt.js';
+import {Frontmatter, Skill} from '../../src/skills/skill.js';
+
+describe('prompt', () => {
+  describe('formatSkillsAsXml', () => {
+    it('returns empty tags for empty skills list', () => {
+      expect(formatSkillsAsXml([])).toBe(
+        '<available_skills>\n</available_skills>',
+      );
+    });
+
+    it('formats a single skill from frontmatter', () => {
+      const skills: Frontmatter[] = [
+        {name: 'test-skill', description: 'A test skill'},
+      ];
+      const expected = `<available_skills>
+  <skill>
+    <name>test-skill</name>
+    <description>A test skill</description>
+  </skill>
+</available_skills>`;
+      expect(formatSkillsAsXml(skills)).toBe(expected);
+    });
+
+    it('formats multiple skills', () => {
+      const skills: Frontmatter[] = [
+        {name: 'skill-1', description: 'Desc 1'},
+        {name: 'skill-2', description: 'Desc 2'},
+      ];
+      const expected = `<available_skills>
+  <skill>
+    <name>skill-1</name>
+    <description>Desc 1</description>
+  </skill>
+  <skill>
+    <name>skill-2</name>
+    <description>Desc 2</description>
+  </skill>
+</available_skills>`;
+      expect(formatSkillsAsXml(skills)).toBe(expected);
+    });
+
+    it('formats skills passed as Skill objects', () => {
+      const skills = [
+        {
+          frontmatter: {name: 'skill-1', description: 'Desc 1'},
+          instructions: 'Instructions 1',
+          resources: {},
+        } as Skill,
+      ];
+      const expected = `<available_skills>
+  <skill>
+    <name>skill-1</name>
+    <description>Desc 1</description>
+  </skill>
+</available_skills>`;
+      expect(formatSkillsAsXml(skills)).toBe(expected);
+    });
+
+    it('escapes HTML entities in name and description', () => {
+      const skills: Frontmatter[] = [
+        {
+          name: 'dangerous<name>',
+          description: 'dangerous&description"with\'quotes',
+        },
+      ];
+      const expected = `<available_skills>
+  <skill>
+    <name>dangerous&lt;name&gt;</name>
+    <description>dangerous&amp;description&quot;with&#039;quotes</description>
+  </skill>
+</available_skills>`;
+      expect(formatSkillsAsXml(skills)).toBe(expected);
+    });
+  });
+});