@agi-cli/sdk 0.1.121 → 0.1.123

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.121",
+	"version": "0.1.123",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",

package/src/core/src/tools/loader.ts

@@ -14,6 +14,7 @@ import { editTool } from './builtin/edit.ts';
 import { buildWebSearchTool } from './builtin/websearch.ts';
 import { buildTerminalTool } from './builtin/terminal.ts';
 import type { TerminalManager } from '../terminals/index.ts';
+import { initializeSkills, buildSkillTool } from '../../../skills/index.ts';
 import fg from 'fast-glob';
 import { dirname, isAbsolute, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -137,6 +138,11 @@ export async function discoverProjectTools(
 		const term = buildTerminalTool(projectRoot, globalTerminalManager);
 		tools.set(term.name, term.tool);
 	}
+	// Skills
+	// Always reinitialize to ensure skills are discovered for the current project
+	await initializeSkills(projectRoot);
+	const skillTool = buildSkillTool();
+	tools.set(skillTool.name, skillTool.tool);
 
 	async function loadFromBase(base: string | null | undefined) {
 		if (!base) return;

package/src/index.ts

@@ -208,3 +208,41 @@ export { z } from './core/src/index.ts';
 // SDK-specific Agent Types
 // =======================
 export type { AgentConfig, AgentConfigEntry } from './agent/types.ts';
+
+// =======================
+// Skills (from internal skills module)
+// =======================
+export type {
+	SkillScope,
+	SkillMetadata,
+	SkillDefinition,
+	DiscoveredSkill,
+	SkillLoadResult,
+	SkillErrorResult,
+	SkillResult,
+} from './skills/index.ts';
+
+export {
+	validateMetadata as validateSkillMetadata,
+	validateSkillName,
+	SkillValidationError,
+} from './skills/index.ts';
+
+export { parseSkillFile, extractFrontmatter } from './skills/index.ts';
+
+export {
+	discoverSkills,
+	loadSkill,
+	getSkillCache,
+	clearSkillCache,
+	findGitRoot,
+	listSkillsInDir,
+} from './skills/index.ts';
+
+export {
+	initializeSkills,
+	getDiscoveredSkills,
+	isSkillsInitialized,
+	buildSkillTool,
+	rebuildSkillDescription,
+} from './skills/index.ts';

package/src/skills/index.ts

@@ -0,0 +1,34 @@
+export type {
+	SkillScope,
+	SkillMetadata,
+	SkillDefinition,
+	DiscoveredSkill,
+	SkillLoadResult,
+	SkillErrorResult,
+	SkillResult,
+} from './types.ts';
+
+export {
+	validateMetadata,
+	validateSkillName,
+	SkillValidationError,
+} from './validator.ts';
+
+export { parseSkillFile, extractFrontmatter } from './parser.ts';
+
+export {
+	discoverSkills,
+	loadSkill,
+	getSkillCache,
+	clearSkillCache,
+	findGitRoot,
+	listSkillsInDir,
+} from './loader.ts';
+
+export {
+	initializeSkills,
+	getDiscoveredSkills,
+	isSkillsInitialized,
+	buildSkillTool,
+	rebuildSkillDescription,
+} from './tool.ts';

package/src/skills/loader.ts

@@ -0,0 +1,152 @@
+import { join, dirname } from 'node:path';
+import { promises as fs } from 'node:fs';
+import fg from 'fast-glob';
+import { parseSkillFile } from './parser.ts';
+import type { SkillDefinition, DiscoveredSkill, SkillScope } from './types.ts';
+import { getGlobalConfigDir, getHomeDir } from '../config/src/paths.ts';
+
+const skillCache = new Map<string, SkillDefinition>();
+
+const SKILL_DIRS = [
+	'.agi/skills',
+	'.claude/skills',
+	'.opencode/skills',
+	'.codex/skills',
+];
+
+export async function discoverSkills(
+	cwd: string,
+	repoRoot?: string,
+): Promise<DiscoveredSkill[]> {
+	const skills = new Map<string, SkillDefinition>();
+	const home = getHomeDir();
+
+	const globalDirs = [
+		join(getGlobalConfigDir(), 'skills'),
+		join(home, '.claude/skills'),
+		join(home, '.config/opencode/skills'),
+		join(home, '.codex/skills'),
+	];
+	for (const dir of globalDirs) {
+		await loadSkillsFromDir(dir, 'user', skills);
+	}
+
+	if (repoRoot && repoRoot !== cwd) {
+		for (const skillDir of SKILL_DIRS) {
+			await loadSkillsFromDir(join(repoRoot, skillDir), 'repo', skills);
+		}
+	}
+
+	let current = cwd;
+	const visited = new Set<string>();
+	while (current && !visited.has(current)) {
+		visited.add(current);
+		const scope: SkillScope =
+			current === cwd ? 'cwd' : current === repoRoot ? 'repo' : 'parent';
+		for (const skillDir of SKILL_DIRS) {
+			await loadSkillsFromDir(join(current, skillDir), scope, skills);
+		}
+		const parent = dirname(current);
+		if (parent === current) break;
+		if (repoRoot && !current.startsWith(repoRoot)) break;
+		current = parent;
+	}
+
+	skillCache.clear();
+	for (const [name, def] of skills) {
+		skillCache.set(name, def);
+	}
+
+	return Array.from(skills.values()).map((s) => ({
+		name: s.metadata.name,
+		description: s.metadata.description,
+		path: s.path,
+		scope: s.scope,
+	}));
+}
+
+export async function loadSkill(name: string): Promise<SkillDefinition | null> {
+	return skillCache.get(name) ?? null;
+}
+
+export function getSkillCache(): Map<string, SkillDefinition> {
+	return skillCache;
+}
+
+export function clearSkillCache(): void {
+	skillCache.clear();
+}
+
+async function loadSkillsFromDir(
+	dir: string,
+	scope: SkillScope,
+	skills: Map<string, SkillDefinition>,
+): Promise<void> {
+	try {
+		await fs.access(dir);
+	} catch {
+		return;
+	}
+
+	const pattern = '*/SKILL.md';
+	let files: string[];
+	try {
+		files = await fg(pattern, { cwd: dir, absolute: true });
+	} catch {
+		return;
+	}
+
+	for (const filePath of files) {
+		try {
+			const content = await fs.readFile(filePath, 'utf-8');
+			const skill = parseSkillFile(content, filePath, scope);
+
+			const dirName = dirname(filePath).split('/').pop();
+			if (dirName !== skill.metadata.name) {
+				if (process.env.AGI_DEBUG === '1') {
+					console.warn(
+						`Skill name '${skill.metadata.name}' doesn't match directory '${dirName}' in ${filePath}`,
+					);
+				}
+			}
+
+			skills.set(skill.metadata.name, skill);
+		} catch (err) {
+			if (process.env.AGI_DEBUG === '1') {
+				console.error(`Failed to load skill from ${filePath}:`, err);
+			}
+		}
+	}
+}
+
+export async function findGitRoot(startDir: string): Promise<string | null> {
+	let current = startDir;
+	const visited = new Set<string>();
+
+	while (current && !visited.has(current)) {
+		visited.add(current);
+		try {
+			await fs.access(join(current, '.git'));
+			return current;
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) break;
+			current = parent;
+		}
+	}
+
+	return null;
+}
+
+export async function listSkillsInDir(dir: string): Promise<string[]> {
+	try {
+		await fs.access(dir);
+	} catch {
+		return [];
+	}
+
+	const pattern = '*/SKILL.md';
+	const files = await fg(pattern, { cwd: dir, absolute: false });
+
+	return files.map((f) => dirname(f));
+}

package/src/skills/parser.ts

@@ -0,0 +1,108 @@
+import type { SkillDefinition, SkillMetadata, SkillScope } from './types.ts';
+import { validateMetadata } from './validator.ts';
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+
+export function parseSkillFile(
+	content: string,
+	path: string,
+	scope: SkillScope,
+): SkillDefinition {
+	const match = content.match(FRONTMATTER_REGEX);
+	if (!match) {
+		throw new Error(`Invalid SKILL.md format: missing frontmatter in ${path}`);
+	}
+
+	const [, yamlStr, body] = match;
+	if (!yamlStr) {
+		throw new Error(`Empty frontmatter in ${path}`);
+	}
+
+	const metadata = parseYamlFrontmatter(yamlStr, path);
+	validateMetadata(metadata, path);
+
+	return {
+		metadata: metadata as SkillMetadata,
+		content: body?.trim() ?? '',
+		path,
+		scope,
+	};
+}
+
+function parseYamlFrontmatter(
+	yaml: string,
+	_path: string,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	const lines = yaml.split('\n');
+	let currentKey: string | null = null;
+	let currentIndent = 0;
+	let nestedObject: Record<string, string> | null = null;
+
+	for (const line of lines) {
+		if (!line.trim()) continue;
+
+		const indent = line.search(/\S/);
+		const trimmed = line.trim();
+
+		if (indent === 0 || (indent <= currentIndent && nestedObject)) {
+			if (nestedObject && currentKey) {
+				result[currentKey] = nestedObject;
+				nestedObject = null;
+				currentKey = null;
+			}
+		}
+
+		const colonIdx = trimmed.indexOf(':');
+		if (colonIdx === -1) continue;
+
+		const key = trimmed.slice(0, colonIdx).trim();
+		const value = trimmed.slice(colonIdx + 1).trim();
+
+		if (indent > 0 && nestedObject) {
+			nestedObject[key] = parseYamlValue(value);
+			continue;
+		}
+
+		if (!value) {
+			currentKey = normalizeKey(key);
+			currentIndent = indent;
+			nestedObject = {};
+			continue;
+		}
+
+		result[normalizeKey(key)] = parseYamlValue(value);
+	}
+
+	if (nestedObject && currentKey) {
+		result[currentKey] = nestedObject;
+	}
+
+	return result;
+}
+
+function normalizeKey(key: string): string {
+	if (key === 'allowed-tools') return 'allowedTools';
+	return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function parseYamlValue(value: string): string {
+	if (
+		(value.startsWith('"') && value.endsWith('"')) ||
+		(value.startsWith("'") && value.endsWith("'"))
+	) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+export function extractFrontmatter(
+	content: string,
+): { frontmatter: string; body: string } | null {
+	const match = content.match(FRONTMATTER_REGEX);
+	if (!match) return null;
+	return {
+		frontmatter: match[1] ?? '',
+		body: match[2] ?? '',
+	};
+}

package/src/skills/tool.ts

@@ -0,0 +1,87 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { loadSkill, discoverSkills, findGitRoot } from './loader.ts';
+import type { DiscoveredSkill, SkillResult } from './types.ts';
+
+let cachedSkillList: DiscoveredSkill[] = [];
+let initializedForPath: string | null = null;
+
+export async function initializeSkills(
+	cwd: string,
+	repoRoot?: string,
+): Promise<DiscoveredSkill[]> {
+	const root = repoRoot ?? (await findGitRoot(cwd)) ?? cwd;
+	cachedSkillList = await discoverSkills(cwd, root);
+	initializedForPath = cwd;
+	return cachedSkillList;
+}
+
+export function getDiscoveredSkills(): DiscoveredSkill[] {
+	return cachedSkillList;
+}
+
+export function isSkillsInitialized(forPath?: string): boolean {
+	if (!initializedForPath) return false;
+	if (forPath && forPath !== initializedForPath) return false;
+	return true;
+}
+
+export function buildSkillTool(): { name: string; tool: Tool } {
+	const skillTool = tool({
+		description: buildSkillDescription(),
+		inputSchema: z.object({
+			name: z.string().describe('Name of the skill to load'),
+		}),
+		async execute({ name }: { name: string }): Promise<SkillResult> {
+			const skill = await loadSkill(name);
+			if (!skill) {
+				return { ok: false, error: `Skill '${name}' not found` };
+			}
+			return {
+				ok: true,
+				name: skill.metadata.name,
+				description: skill.metadata.description,
+				content: skill.content,
+				path: skill.path,
+				scope: skill.scope,
+				allowedTools: skill.metadata.allowedTools,
+			};
+		},
+	});
+
+	return { name: 'skill', tool: skillTool };
+}
+
+function buildSkillDescription(): string {
+	if (cachedSkillList.length === 0) {
+		return 'Load a skill by name. No skills are currently available.';
+	}
+
+	const skillsXml = cachedSkillList
+		.map(
+			(s) =>
+				`<skill><name>${escapeXml(s.name)}</name><description>${escapeXml(s.description)}</description></skill>`,
+		)
+		.join('\n');
+
+	return `Load a skill by name to get detailed instructions.
+
+<available_skills>
+${skillsXml}
+</available_skills>
+
+Call this tool with the skill name when you need the full instructions.`;
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;');
+}
+
+export function rebuildSkillDescription(): string {
+	return buildSkillDescription();
+}

package/src/skills/types.ts

@@ -0,0 +1,41 @@
+export type SkillScope = 'cwd' | 'parent' | 'repo' | 'user' | 'system';
+
+export interface SkillMetadata {
+	name: string;
+	description: string;
+	license?: string;
+	compatibility?: string;
+	metadata?: Record<string, string>;
+	allowedTools?: string[];
+}
+
+export interface SkillDefinition {
+	metadata: SkillMetadata;
+	content: string;
+	path: string;
+	scope: SkillScope;
+}
+
+export interface DiscoveredSkill {
+	name: string;
+	description: string;
+	path: string;
+	scope: SkillScope;
+}
+
+export interface SkillLoadResult {
+	ok: true;
+	name: string;
+	description: string;
+	content: string;
+	path: string;
+	scope: SkillScope;
+	allowedTools?: string[];
+}
+
+export interface SkillErrorResult {
+	ok: false;
+	error: string;
+}
+
+export type SkillResult = SkillLoadResult | SkillErrorResult;

package/src/skills/validator.ts

@@ -0,0 +1,110 @@
+import type { SkillMetadata } from './types.ts';
+
+const NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_COMPATIBILITY_LENGTH = 500;
+
+export class SkillValidationError extends Error {
+	constructor(
+		message: string,
+		public path: string,
+	) {
+		super(message);
+		this.name = 'SkillValidationError';
+	}
+}
+
+export function validateMetadata(
+	meta: unknown,
+	path: string,
+): asserts meta is SkillMetadata {
+	if (!meta || typeof meta !== 'object') {
+		throw new SkillValidationError(`Invalid frontmatter in ${path}`, path);
+	}
+
+	const m = meta as Record<string, unknown>;
+
+	if (typeof m.name !== 'string' || !m.name) {
+		throw new SkillValidationError(
+			`Missing required 'name' field in ${path}`,
+			path,
+		);
+	}
+	if (m.name.length > MAX_NAME_LENGTH) {
+		throw new SkillValidationError(
+			`Skill name exceeds ${MAX_NAME_LENGTH} chars in ${path}`,
+			path,
+		);
+	}
+	if (!NAME_REGEX.test(m.name)) {
+		throw new SkillValidationError(
+			`Invalid skill name '${m.name}' - must be lowercase alphanumeric with hyphens, no start/end hyphens, no consecutive hyphens`,
+			path,
+		);
+	}
+
+	if (typeof m.description !== 'string' || !m.description) {
+		throw new SkillValidationError(
+			`Missing required 'description' field in ${path}`,
+			path,
+		);
+	}
+	if (m.description.length > MAX_DESCRIPTION_LENGTH) {
+		throw new SkillValidationError(
+			`Description exceeds ${MAX_DESCRIPTION_LENGTH} chars in ${path}`,
+			path,
+		);
+	}
+
+	if (
+		m.compatibility &&
+		typeof m.compatibility === 'string' &&
+		m.compatibility.length > MAX_COMPATIBILITY_LENGTH
+	) {
+		throw new SkillValidationError(
+			`Compatibility exceeds ${MAX_COMPATIBILITY_LENGTH} chars in ${path}`,
+			path,
+		);
+	}
+
+	if (m.metadata !== undefined) {
+		if (typeof m.metadata !== 'object' || m.metadata === null) {
+			throw new SkillValidationError(
+				`metadata must be an object in ${path}`,
+				path,
+			);
+		}
+		for (const [key, value] of Object.entries(
+			m.metadata as Record<string, unknown>,
+		)) {
+			if (typeof value !== 'string') {
+				throw new SkillValidationError(
+					`metadata.${key} must be a string in ${path}`,
+					path,
+				);
+			}
+		}
+	}
+
+	if (m['allowed-tools'] !== undefined && m.allowedTools === undefined) {
+		m.allowedTools = m['allowed-tools'];
+	}
+
+	if (m.allowedTools !== undefined) {
+		if (typeof m.allowedTools === 'string') {
+			m.allowedTools = m.allowedTools.split(/\s+/).filter(Boolean);
+		}
+		if (!Array.isArray(m.allowedTools)) {
+			throw new SkillValidationError(
+				`allowed-tools must be a string or array in ${path}`,
+				path,
+			);
+		}
+	}
+}
+
+export function validateSkillName(name: string): boolean {
+	if (!name || name.length > MAX_NAME_LENGTH) return false;
+	return NAME_REGEX.test(name);
+}