@vincemakes/kiso-skills-ext 0.39.2 → 0.40.1

package/README.md

@@ -17,6 +17,27 @@ 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.
 
+## Invoking a skill yourself
+
+`/skill <name> [args]` sends a skill as your turn: its SKILL.md body, then
+your args after a blank line. `/<name> [args]` does the same when no
+built-in command has that name — a built-in always wins. `/skills` lists
+what is installed, where each skill lives, and any that cannot load with
+the reason.
+
+The frontmatter keys read are `name`, `description` and `user-invocable`.
+Values may be plain, quoted (`"…"` or `'…'`), or YAML block scalars (`>` or
+`|`, with the text on the following indented lines); the index shows the
+description on one line. A `>` or `|` with nothing under it is reported as
+a skill that cannot load.
+
+A skill whose frontmatter says `user-invocable: false` stays in the
+model's index and out of your reach. Only the literal `false` counts; a
+skill without the key is invocable.
+
+The body is sent as written — there is no placeholder substitution; your
+args follow it. A body over 32,768 characters is refused, not cut.
+
 ## Versioning
 
 The version counter is this package's own. It is pinned exactly by the kiso

package/dist/kiso-skills.mjs

@@ -4,7 +4,8 @@
  *
  * 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
+ * name/description/user-invocable 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>
@@ -41,7 +42,8 @@ export default async function createSkillsExtension() {
 	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", skills: 0, tools: [] };
+	const catalog = skillsCatalog(index, broken);
+	if (index.length === 0 && broken.length === 0) return { name: "skills", skills: 0, tools: [], catalog };
 	const tools = index.length > 0 ? [readSkillTool(index, broken)] : [];
 	return {
 		name: "skills",
@@ -50,6 +52,10 @@ export default async function createSkillsExtension() {
 		// it here rather than walking the directory again — one scan, one
 		// answer, and no second count free to disagree with this one.
 		skills: index.length,
+		// 0.40.0: the same scan, handed to the CLI for `/skill` and
+		// `/skills` — the person's door and the model's index cannot list
+		// different skills, because they are one list.
+		catalog,
 		systemPrompt: { append: skillsPromptAppend(index, broken) },
 	};
 }
@@ -73,9 +79,9 @@ function loadIndex(skillsDir) {
 			} 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)`);
+					else brokenLinks.push({ dir: d.name, reason: "symlink target is not a directory" });
 				} catch {
-					brokenLinks.push(`${d.name} (broken symlink)`);
+					brokenLinks.push({ dir: d.name, reason: "broken symlink" });
 				}
 			}
 		}
@@ -90,38 +96,126 @@ function loadIndex(skillsDir) {
 		try {
 			text = readFileSync(path, "utf8");
 		} catch {
-			broken.push(`${dir} (no SKILL.md)`);
+			broken.push({ dir, reason: "no SKILL.md" });
 			continue;
 		}
-		const meta = parseFrontmatter(text);
-		if (meta === null) {
-			broken.push(`${dir} (no frontmatter)`);
+		const parsed = parseFrontmatter(text);
+		if (parsed === null) {
+			broken.push({ dir, reason: "no frontmatter" });
+			continue;
+		}
+		const { meta, emptyBlocks } = parsed;
+		// RF-2: a `>`/`|` with nothing under it is a mistake in the file, not
+		// an empty value — say so, rather than "no description"
+		if (emptyBlocks.has("name") || emptyBlocks.has("description")) {
+			broken.push({ dir, reason: "empty block scalar" });
 			continue;
 		}
 		const name = (meta.name ?? dir).trim();
-		let description = (meta.description ?? "").trim();
+		// RF-2: a name is matched against `/skill <name>` and printed on one
+		// index line — a `|` block or a quoted "\n" cannot make it two
+		if (/[\r\n]/.test(name)) {
+			broken.push({ dir, reason: "name is not one line" });
+			continue;
+		}
+		// the index is ONE line per skill: only a value that CARRIES a newline
+		// (a `|` block, a quoted "\n") is collapsed — a plain value's bytes are
+		// exactly what they were before RF-2, inner spacing included
+		const rawDescription = meta.description ?? "";
+		let description = (/[\r\n]/.test(rawDescription) ? rawDescription.replace(/\s+/g, " ") : rawDescription).trim();
 		if (description === "") {
-			broken.push(`${dir} (no description)`);
+			broken.push({ dir, reason: "no description" });
 			continue;
 		}
 		if (description.length > MAX_DESCRIPTION) description = `${description.slice(0, MAX_DESCRIPTION)}…[truncated]`;
-		index.push({ name, description, path });
+		// `user-invocable: false` (the key other harnesses use) keeps a skill
+		// out of the person's reach and in the model's. Only the literal
+		// `false` counts: absence cannot be told apart from a skill written
+		// before the key existed, so absence is invocable.
+		index.push({ name, description, dir, path, userInvocable: meta["user-invocable"] !== "false" });
 	}
 	return { index, broken };
 }
 
-/** The --- wrapped YAML subset: only `name:` and `description:` lines are
- *  read (everything else is ignored). Null = no valid frontmatter. */
+/** 0.40.0 — what the CLI reads to let a PERSON invoke a skill. `body` reads
+ *  the file at call time (finding #8: nothing is held), strips the
+ *  frontmatter, and refuses — never truncates — a body over the cap: a
+ *  skill cut in half is a different instruction than the one written. */
+function skillsCatalog(index, broken) {
+	return {
+		entries: index.map(({ name, description, dir, path, userInvocable }) => ({ name, description, dir, path, userInvocable })),
+		broken: broken.map(({ dir, reason }) => ({ dir, reason })),
+		body(name) {
+			const skill = index.find((s) => s.name === name);
+			if (skill === undefined) return { error: "not installed" };
+			let text;
+			try {
+				text = readFileSync(skill.path, "utf8");
+			} catch (err) {
+				return { error: `cannot read ${skill.path}: ${err instanceof Error ? err.message : String(err)}` };
+			}
+			const end = text.indexOf("\n---", 4);
+			const body = text.slice(end + 4).replace(/^[^\n]*\n?/, "").trim();
+			if (body.length > MAX_BODY) return { error: `over the ${MAX_BODY.toLocaleString("en-US")}-character skill cap (${body.length.toLocaleString("en-US")} characters)` };
+			return { body };
+		},
+	};
+}
+
+/** The --- wrapped YAML subset: top-level `key: value` lines; the loader
+ *  reads `name`, `description` and `user-invocable` (everything else is
+ *  ignored). Null = no valid frontmatter.
+ *
+ *  RF-2: skills written for other harnesses use real YAML, so a value may
+ *  be a BLOCK scalar (`>` folds its lines with spaces, `|` keeps them; an
+ *  optional chomping `+`/`-` is accepted) whose text is the following lines
+ *  indented deeper than the key, or a double/single-QUOTED scalar. The flat
+ *  reader indexed `description: >` as the literal ">" and dropped the text.
+ *  A block indicator with no indented lines records the key in
+ *  `emptyBlocks` — the caller names it a broken entry, never an empty
+ *  description. Anchors, flow collections and nesting stay out of scope:
+ *  the index needs three string keys. */
 function parseFrontmatter(text) {
 	if (!text.startsWith("---\n")) return null;
 	const end = text.indexOf("\n---", 4);
 	if (end < 0) return null;
+	const lines = text.slice(4, end).split("\n");
 	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();
+	const emptyBlocks = new Set();
+	for (let i = 0; i < lines.length; i += 1) {
+		const m = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(lines[i]);
+		if (m === null) continue;
+		const [, key, rawValue] = m;
+		const value = rawValue.trim();
+		if (/^[>|][+-]?$/.test(value)) {
+			// the block: every following line indented deeper than the key
+			// (a blank line inside the block belongs to it)
+			const block = [];
+			while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || (lines[i + 1].trim() === "" && block.length > 0))) block.push(lines[(i += 1)]);
+			while (block.length > 0 && block[block.length - 1].trim() === "") block.pop();
+			if (block.length === 0) {
+				emptyBlocks.add(key);
+				meta[key] = "";
+				continue;
+			}
+			const indent = Math.min(...block.filter((l) => l.trim() !== "").map((l) => /^\s*/.exec(l)[0].length));
+			const body = block.map((l) => l.slice(indent));
+			meta[key] = value.startsWith(">") ? body.map((l) => l.trim()).join(" ").replace(/ {2,}/g, " ").trim() : body.join("\n").trim();
+		} else {
+			meta[key] = unquote(value);
+		}
+	}
+	return { meta, emptyBlocks };
+}
+
+/** RF-2: a quoted scalar's text — `"…"` with its backslash escapes, `'…'`
+ *  with `''` for a quote. Anything else is returned as written. */
+function unquote(value) {
+	if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+		return value.slice(1, -1).replace(/\\(["\\nt])/g, (_, c) => (c === "n" ? "\n" : c === "t" ? "\t" : c));
 	}
-	return meta;
+	if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1).replace(/''/g, "'");
+	return value;
 }
 
 /** Tier 1: the resident index — one line per skill, sorted by directory
@@ -129,14 +223,14 @@ function parseFrontmatter(text) {
 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(", ")}` : "";
+		broken.length > 0 ? `\n[skills] skipped ${broken.length} broken skill(s): ${broken.map((b) => `${b.dir} (${b.reason})`).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(", ")})` : "";
+	const brokenNote = broken.length > 0 ? ` (${broken.length} broken skill(s) skipped: ${broken.map((b) => b.dir).join(", ")})` : "";
 	return {
 		name: "read_skill",
 		description: "load a skill's SKILL.md (the available-skills list is in the system prompt)",

package/index.d.ts

@@ -11,7 +11,25 @@ import type { KisoExtension } from "@vincemakes/kiso-core";
  *  caller wanting the number does not walk the directory a second time and
  *  get a second answer free to disagree with this one. Absent means the
  *  load reported none — never a reason to guess. */
-type SkillsExtension = KisoExtension & { readonly skills?: number };
+type SkillsExtension = KisoExtension & { readonly skills?: number; readonly catalog?: SkillsCatalog };
+
+/** 0.40.0: the same scan, for the CLI's `/skill` and `/skills`. `body` reads
+ *  the file at call time and returns the SKILL.md body without its
+ *  frontmatter, or the reason it cannot (over the cap, unreadable). */
+export interface SkillsCatalog {
+	readonly entries: readonly {
+		readonly name: string;
+		readonly description: string;
+		/** the directory under the skills root the skill was found in */
+		readonly dir: string;
+		readonly path: string;
+		/** false only for `user-invocable: false` — the model may still load it */
+		readonly userInvocable: boolean;
+	}[];
+	/** the loader's own reason per skipped entry — the words the model's warning line uses */
+	readonly broken: readonly { readonly dir: string; readonly reason: string }[];
+	body(name: string): { readonly body: string } | { readonly error: string };
+}
 
 declare const createSkillsExtension: () => SkillsExtension | Promise<SkillsExtension>;
 export default createSkillsExtension;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-skills-ext",
-	"version": "0.39.2",
+	"version": "0.40.1",
 	"description": "kiso official skills extension \u2014 two-tier progressive skills, kernel untouched",
 	"type": "module",
 	"license": "MIT",
@@ -23,7 +23,7 @@
 		"test": "vitest run"
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-core": "0.39.2",
+		"@vincemakes/kiso-core": "0.40.1",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"