@dex-ai/skills-extension 0.2.3

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dex-ai/skills-extension",
+  "version": "0.2.3",
+  "description": "File-based skill loader for @dex-ai/sdk — loads skills from ~/.dex/skills/ directories.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "zod": "^3.23.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/index.ts

@@ -0,0 +1,334 @@
+/**
+ * @dex-ai/skills-extension — file-based skill loader.
+ *
+ * Loads skills from ~/.dex/skills/ directories. Each skill is a folder
+ * containing a SKILL.md entry point (with optional YAML frontmatter).
+ *
+ * Skills follow the same format as Claude Code skills:
+ *   ~/.dex/skills/<name>/SKILL.md
+ *
+ * Extensions can also bundle their own skills using the loadSkill() helper.
+ *
+ * Usage:
+ *   import { skillsExtension } from '@dex-ai/skills-extension';
+ *
+ *   const agent = await Agent.create({
+ *     extensions: [skillsExtension(), ...otherExtensions],
+ *   });
+ */
+
+import type {
+	Extension,
+	Skill,
+	Tool,
+	ToolOutput,
+	AgentContext,
+} from "@dex-ai/sdk";
+import { z } from "zod";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+
+/* ------------------------------------------------------------------ */
+/* SKILL.md Parsing                                                    */
+/* ------------------------------------------------------------------ */
+
+export interface ParsedSkill {
+	/** Skill name (from frontmatter or directory name). */
+	name: string;
+	/** Short description for the catalog listing. */
+	description?: string;
+	/** Tools auto-approved when this skill is active. */
+	allowedTools?: string[];
+	/** The skill content (markdown body minus frontmatter). */
+	content: string;
+	/** Absolute path to the skill directory. */
+	dir: string;
+	/** List of supporting files (relative paths). */
+	files: string[];
+}
+
+/**
+ * Parse YAML frontmatter from a SKILL.md string.
+ * Returns the frontmatter fields and the remaining body.
+ */
+function parseFrontmatter(raw: string): {
+	meta: Record<string, unknown>;
+	body: string;
+} {
+	const trimmed = raw.trimStart();
+	if (!trimmed.startsWith("---")) {
+		return { meta: {}, body: raw };
+	}
+
+	const endIdx = trimmed.indexOf("\n---", 3);
+	if (endIdx === -1) {
+		return { meta: {}, body: raw };
+	}
+
+	const yamlBlock = trimmed.slice(4, endIdx); // after opening ---\n
+	const body = trimmed.slice(endIdx + 4).trimStart(); // after closing ---\n
+
+	// Simple YAML parser for flat key: value pairs
+	const meta: Record<string, unknown> = {};
+	for (const line of yamlBlock.split("\n")) {
+		const match = line.match(/^(\w[\w-]*)\s*:\s*(.+)$/);
+		if (match) {
+			const key = match[1]!;
+			let value: unknown = match[2]!.trim();
+
+			// Remove surrounding quotes
+			if (
+				typeof value === "string" &&
+				((value.startsWith('"') && value.endsWith('"')) ||
+					(value.startsWith("'") && value.endsWith("'")))
+			) {
+				value = (value as string).slice(1, -1);
+			}
+
+			meta[key] = value;
+		}
+	}
+
+	return { meta, body };
+}
+
+/**
+ * List supporting files in a skill directory (excluding SKILL.md itself).
+ */
+function listSupportingFiles(skillDir: string): string[] {
+	const files: string[] = [];
+
+	function walk(dir: string, prefix: string) {
+		let entries: string[];
+		try {
+			entries = readdirSync(dir);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry === "node_modules" || entry.startsWith(".")) continue;
+			const full = join(dir, entry);
+			const rel = prefix ? `${prefix}/${entry}` : entry;
+			try {
+				if (statSync(full).isDirectory()) {
+					walk(full, rel);
+				} else if (entry !== "SKILL.md") {
+					files.push(rel);
+				}
+			} catch {
+				// skip unreadable
+			}
+		}
+	}
+
+	walk(skillDir, "");
+	return files;
+}
+
+/**
+ * Load a SKILL.md from a directory. Used by extensions to bundle skills
+ * in the same format as user-defined file-based skills.
+ *
+ * @param skillDir - Absolute path to the skill directory containing SKILL.md.
+ * @returns A Skill object ready to put on ext.skills.
+ */
+export function loadSkill(skillDir: string): Skill {
+	const parsed = parseSkillDir(skillDir);
+	return {
+		name: parsed.name,
+		...(parsed.description !== undefined
+			? { description: parsed.description }
+			: {}),
+		content: parsed.content,
+	};
+}
+
+/**
+ * Parse a skill directory into a ParsedSkill.
+ */
+function parseSkillDir(skillDir: string): ParsedSkill {
+	const skillMdPath = join(skillDir, "SKILL.md");
+	if (!existsSync(skillMdPath)) {
+		throw new Error(`SKILL.md not found in ${skillDir}`);
+	}
+
+	const raw = readFileSync(skillMdPath, "utf-8");
+	const { meta, body } = parseFrontmatter(raw);
+
+	const name = typeof meta.name === "string" ? meta.name : basename(skillDir);
+
+	let allowedTools: string[] | undefined;
+	if (typeof meta["allowed-tools"] === "string") {
+		allowedTools = (meta["allowed-tools"] as string)
+			.split(/\s+/)
+			.filter(Boolean);
+	}
+
+	const files = listSupportingFiles(skillDir);
+
+	return {
+		name,
+		...(typeof meta.description === "string"
+			? { description: meta.description }
+			: {}),
+		...(allowedTools !== undefined ? { allowedTools } : {}),
+		content: body,
+		dir: skillDir,
+		files,
+	};
+}
+
+/**
+ * Scan a directory for skill subdirectories (each containing SKILL.md).
+ */
+function scanSkillsDir(dir: string): ParsedSkill[] {
+	if (!existsSync(dir)) return [];
+
+	const skills: ParsedSkill[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+
+	for (const entry of entries) {
+		const skillDir = join(dir, entry);
+		try {
+			if (!statSync(skillDir).isDirectory()) continue;
+			const skillMd = join(skillDir, "SKILL.md");
+			if (!existsSync(skillMd)) continue;
+			skills.push(parseSkillDir(skillDir));
+		} catch {
+			// skip unreadable entries
+		}
+	}
+
+	return skills;
+}
+
+/* ------------------------------------------------------------------ */
+/* get_skill tool                                                      */
+/* ------------------------------------------------------------------ */
+
+const getSkillParams = z.object({
+	name: z
+		.string()
+		.min(1)
+		.describe("The skill name from the catalog to retrieve."),
+	file: z
+		.string()
+		.optional()
+		.describe("Optional supporting file path within the skill directory."),
+});
+
+function getSkillTool(parsedSkills: Map<string, ParsedSkill>): Tool {
+	return {
+		name: "get_skill",
+		displayName: "Skill",
+		visible: false,
+		access: "read",
+		description:
+			"Retrieve the full content of a skill by name. Use when you need detailed instructions from the skills catalog.",
+		parameters: getSkillParams,
+		execute(input, gctx): ToolOutput {
+			const parsed = getSkillParams.parse(input);
+
+			// Try the parsed skills registry first (has file access)
+			const skill = parsedSkills.get(parsed.name);
+
+			if (!parsed.file) {
+				// Return skill content from state (includes all skills from all extensions)
+				const skillMap = gctx.agent.state.get("skills") as
+					| Map<string, string>
+					| undefined;
+				if (!skillMap) {
+					return { type: "error-text", value: "No skills available." };
+				}
+				const content = skillMap.get(parsed.name);
+				if (!content) {
+					const available = [...skillMap.keys()].join(", ");
+					return {
+						type: "error-text",
+						value: `Skill "${parsed.name}" not found. Available: ${available}`,
+					};
+				}
+
+				// If we have the parsed skill with supporting files, append file listing
+				let result = content;
+				if (skill && skill.files.length > 0) {
+					result += `\n\n## Supporting Files\n\n${skill.files.map((f) => `- ${f}`).join("\n")}\n\nUse \`get_skill\` with the \`file\` parameter to read any supporting file.`;
+				}
+				return { type: "text", value: result };
+			}
+
+			// File access — only available for parsed skills (file-based)
+			if (!skill) {
+				return {
+					type: "error-text",
+					value: `Skill "${parsed.name}" does not support file access (not a file-based skill).`,
+				};
+			}
+
+			const filePath = join(skill.dir, parsed.file);
+			// Security: ensure the resolved path is within the skill directory
+			if (!filePath.startsWith(skill.dir)) {
+				return { type: "error-text", value: "Path traversal not allowed." };
+			}
+
+			try {
+				const content = readFileSync(filePath, "utf-8");
+				return { type: "text", value: content };
+			} catch {
+				return {
+					type: "error-text",
+					value: `File "${parsed.file}" not found in skill "${parsed.name}". Available: ${skill.files.join(", ") || "(none)"}`,
+				};
+			}
+		},
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension options                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface SkillsExtensionOptions {
+	/** Directories to scan for skill folders. Default: ['~/.dex/skills'] */
+	dirs?: string[];
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export function skillsExtension(opts: SkillsExtensionOptions = {}): Extension {
+	const dirs = opts.dirs ?? [join(homedir(), ".dex", "skills")];
+
+	// Scan skill directories and load all skills
+	const parsedSkills = new Map<string, ParsedSkill>();
+	for (const dir of dirs) {
+		for (const skill of scanSkillsDir(dir)) {
+			parsedSkills.set(skill.name, skill);
+		}
+	}
+
+	// Convert to SDK Skill objects for the ext.skills field
+	const skills: Skill[] = [];
+	for (const [, parsed] of parsedSkills) {
+		skills.push({
+			name: parsed.name,
+			...(parsed.description !== undefined
+				? { description: parsed.description }
+				: {}),
+			content: parsed.content,
+		});
+	}
+
+	return {
+		name: "skills",
+		skills,
+		tools: [getSkillTool(parsedSkills)],
+	};
+}