@vincemakes/kiso-skills-ext 0.1.45

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# kiso-skills-ext
+
+The kiso official skills extension: two-tier progressive skills, the kernel
+untouched.
+
+## How it is loaded
+
+Since 0.1.45 this extension ships **built-in** with the kiso CLI — a fresh
+install starts with it registered (the startup banner lists it), with zero
+disk setup. The same artifact can also be installed as a user-level
+extension: copy `dist/kiso-skills.mjs` into `~/.kiso/extensions/` — the
+user-layer loader accepts exactly this shape.
+
+## Configuration
+
+Skill directories: `~/.kiso/skills/<name>/SKILL.md` (or the project-level
+`.kiso/skills/` after the trust gate). No configuration file — the
+extension scans the skills dir at startup.
+
+## Versioning
+
+The version counter is this package's own. It is pinned exactly by the kiso
+CLI it ships with; an extension release reaches CLI users through the next
+CLI release.

package/dist/kiso-skills.mjs

@@ -0,0 +1,163 @@
+/**
+ * kiso (foundation) official skills extension — ⑤: two-tier progressive skills,
+ * kernel untouched.
+ *
+ * Tier 1 (resident): the skills index — every ${KISO_SKILLS_DIR:-~/.kiso/
+ * skills}/<name>/SKILL.md's frontmatter (a --- wrapped YAML SUBSET; only
+ * name/description are read, by a hand-written parser — no deps) becomes
+ * one line of the system prompt, sorted by directory name:
+ *   Available skills (load with read_skill):
+ *   - <name>: <description>
+ * A SKILL.md without frontmatter is skipped with a warning line at the
+ * tail of that index (soft failure — the mcp philosophy). No/empty skills
+ * dir → an empty extension, never an error.
+ *
+ * Tier 2 (on demand): the read_skill tool returns the FULL SKILL.md (capped
+ * at 32KB with a truncation note); an unknown name is an honest,
+ * actionable error listing the installed skills. Files other than
+ * SKILL.md are NOT auto-loaded — the body tells the model to read them
+ * with read_file by relative path (the progressive third tier; zero new
+ * mechanisms).
+ *
+ * Compatible with Claude Code skills: the frontmatter name/description
+ * subset parses CC skill files — drop one in and it works.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAX_DESCRIPTION = 200;
+const MAX_BODY = 32 * 1024;
+
+/** finding #11: KISO_HOME is the ONE root — the default skills dir derives
+ *  from it (KISO_SKILLS_DIR still overrides). */
+function kisoHome() {
+	return process.env.KISO_HOME ?? join(homedir(), ".kiso");
+}
+
+export default async function createSkillsExtension() {
+	const skillsDir = process.env.KISO_SKILLS_DIR ?? join(kisoHome(), "skills");
+	const { index, broken } = loadIndex(skillsDir);
+	// finding #8: no persistent resources — SKILL.md files are read per call;
+	// nothing is spawned or connected — no dispose is needed, explicitly.
+	if (index.length === 0 && broken.length === 0) return { name: "skills", tools: [] };
+	const tools = index.length > 0 ? [readSkillTool(index, broken)] : [];
+	return {
+		name: "skills",
+		tools,
+		systemPrompt: { append: skillsPromptAppend(index, broken) },
+	};
+}
+
+/** Scan ${dir}/<name>/SKILL.md, parse the frontmatter subset, sort by
+ *  directory name. Broken entries are SOFT failures — recorded, skipped.
+ *  finding #9 (P2): a symlink to a directory IS a skill dir — the
+ *  CC-compatible migration path (`ln -s ~/.claude/skills/x
+ *  ~/.kiso/skills/x`) must work; a broken link (target missing or not a
+ *  directory) is a soft failure like any other broken skill, never an
+ *  error. */
+function loadIndex(skillsDir) {
+	let dirs;
+	let brokenLinks = [];
+	try {
+		const entries = readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+		dirs = [];
+		for (const d of entries) {
+			if (d.isDirectory()) {
+				dirs.push(d.name);
+			} else if (d.isSymbolicLink()) {
+				try {
+					if (statSync(join(skillsDir, d.name)).isDirectory()) dirs.push(d.name);
+					else brokenLinks.push(`${d.name} (symlink target is not a directory)`);
+				} catch {
+					brokenLinks.push(`${d.name} (broken symlink)`);
+				}
+			}
+		}
+	} catch {
+		return { index: [], broken: [] }; // no skills dir = no skills, never an error
+	}
+	const index = [];
+	const broken = brokenLinks; // finding #9: broken links join the existing soft-failure path
+	for (const dir of dirs) {
+		const path = join(skillsDir, dir, "SKILL.md");
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			broken.push(`${dir} (no SKILL.md)`);
+			continue;
+		}
+		const meta = parseFrontmatter(text);
+		if (meta === null) {
+			broken.push(`${dir} (no frontmatter)`);
+			continue;
+		}
+		const name = (meta.name ?? dir).trim();
+		let description = (meta.description ?? "").trim();
+		if (description === "") {
+			broken.push(`${dir} (no description)`);
+			continue;
+		}
+		if (description.length > MAX_DESCRIPTION) description = `${description.slice(0, MAX_DESCRIPTION)}…[truncated]`;
+		index.push({ name, description, path });
+	}
+	return { index, broken };
+}
+
+/** The --- wrapped YAML subset: only `name:` and `description:` lines are
+ *  read (everything else is ignored). Null = no valid frontmatter. */
+function parseFrontmatter(text) {
+	if (!text.startsWith("---\n")) return null;
+	const end = text.indexOf("\n---", 4);
+	if (end < 0) return null;
+	const meta = {};
+	for (const line of text.slice(4, end).split("\n")) {
+		const m = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+		if (m !== null) meta[m[1]] = m[2].trim();
+	}
+	return meta;
+}
+
+/** Tier 1: the resident index — one line per skill, sorted by directory
+ *  name, a warning line for every broken entry at the tail. */
+function skillsPromptAppend(index, broken) {
+	const lines = index.map((s) => `- ${s.name}: ${s.description}`);
+	const warning =
+		broken.length > 0 ? `\n[skills] skipped ${broken.length} broken skill(s): ${broken.join(", ")}` : "";
+	return `Available skills (load with read_skill):\n${lines.join("\n")}${warning}`;
+}
+
+/** Tier 2: read_skill — the full SKILL.md (≤32KB), or an honest,
+ *  actionable unknown-name error listing the installed skills. */
+function readSkillTool(index, broken) {
+	const brokenNote = broken.length > 0 ? ` (${broken.length} broken skill(s) skipped: ${broken.map((b) => b.split(" ")[0]).join(", ")})` : "";
+	return {
+		name: "read_skill",
+		description: "load a skill's SKILL.md (the available-skills list is in the system prompt)",
+		parameters: { type: "object", properties: { name: { type: "string", minLength: 1 } }, required: ["name"] },
+		execute: async (input) => {
+			const name = String((input ?? {}).name ?? "");
+			const skill = index.find((s) => s.name === name);
+			if (skill === undefined) {
+				const names = index.length > 0 ? index.map((s) => s.name).join(", ") : "(none installed)";
+				return {
+					content: `[skills] unknown skill "${name}" — available: ${names}${brokenNote}`,
+					isError: true,
+					errorKind: "invalid_input",
+				};
+			}
+			let text;
+			try {
+				text = readFileSync(skill.path, "utf8");
+			} catch (err) {
+				return { content: `[skills] cannot read ${skill.path}: ${err instanceof Error ? err.message : String(err)}`, isError: true, errorKind: "fatal" };
+			}
+			if (text.length > MAX_BODY) {
+				text = `${text.slice(0, MAX_BODY)}\n…[truncated at ${MAX_BODY} chars — read the rest with read_file]`;
+			}
+			return { content: text, isError: false };
+		},
+	};
+}

package/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The published type surface of @vincemakes/kiso-skills-ext: the default
+ * export is the FACTORY (the same contract the user-layer disk loader
+ * accepts — a KisoExtension or a factory returning one). The type import
+ * from kiso-core is compile-time only — the shipped bundle is
+ * self-contained, zero runtime dependencies.
+ */
+import type { KisoExtension } from "@vincemakes/kiso-core";
+
+declare const createSkillsExtension: () => KisoExtension | Promise<KisoExtension>;
+export default createSkillsExtension;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vincemakes/kiso-skills-ext",
+  "version": "0.1.45",
+  "description": "kiso official skills extension \u2014 two-tier progressive skills, kernel untouched",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/kiso-skills.mjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/kiso-skills.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@vincemakes/kiso-core": "0.1.35",
+    "@types/node": "^26.1.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}