@vincemakes/kiso-skills-ext 0.44.0 → 0.45.0

package/README.md

@@ -17,6 +17,17 @@ 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.
 
+A name found twice resolves to its first occurrence (root order, then
+directory-name order within each root); the later one is reported with
+the broken skills, never listed.
+
+A host passes options instead: `createSkillsExtension({ roots, include })`.
+`roots` replaces the default scan with the host's directories, in order.
+`include(entry)` decides which skills are active, and the model's index,
+`read_skill`, the catalog and the count are all built from that one
+filtered list, so a skill the host turned off cannot be loaded on
+request either.
+
 ## Invoking a skill yourself
 
 `/skill <name> [args]` sends a skill as your turn: its SKILL.md body, then

package/dist/kiso-skills.mjs

@@ -37,9 +37,19 @@ 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);
+/**
+ * `options` are for a host; the CLI passes none.
+ * - `roots`: directories to scan, in order. Given, they replace the
+ *   default (KISO_SKILLS_DIR, else $KISO_HOME/skills); the env var is not read.
+ * - `include(entry)`: false drops the skill from the ONE active index that
+ *   the prompt, `read_skill`, the catalog and the count are all built
+ *   from, so no surface can offer a skill another one hides. `broken`
+ *   (installation diagnostics) is not filtered.
+ */
+export default async function createSkillsExtension(options = {}) {
+	const roots = options.roots ?? [process.env.KISO_SKILLS_DIR ?? join(kisoHome(), "skills")];
+	const { index: loaded, broken } = firstNameWins(roots.map((root) => loadIndex(root)));
+	const index = options.include === undefined ? loaded : loaded.filter((s) => options.include(entryOf(s)));
 	// finding #8: no persistent resources — SKILL.md files are read per call;
 	// nothing is spawned or connected — no dispose is needed, explicitly.
 	const catalog = skillsCatalog(index, broken);
@@ -137,13 +147,43 @@ function loadIndex(skillsDir) {
 	return { index, broken };
 }
 
+/** A name found twice resolves to its FIRST occurrence — root order, then
+ *  the directory sort within a root — and every later one is reported in
+ *  `broken`, never listed. `read_skill` always served the first; the index
+ *  used to list both, offering a skill nobody could load. Resolved before
+ *  a host's `include`, so a filter cannot change which one wins. */
+function firstNameWins(scans) {
+	const index = [];
+	const broken = [];
+	const winners = new Map();
+	scans.forEach((scan, root) => {
+		broken.push(...scan.broken);
+		for (const skill of scan.index) {
+			const first = winners.get(skill.name);
+			if (first === undefined) {
+				winners.set(skill.name, { skill, root });
+				index.push(skill);
+				continue;
+			}
+			const where = first.root === root ? first.skill.dir : `${first.skill.dir} in an earlier root`;
+			broken.push({ dir: skill.dir, reason: `duplicate name "${skill.name}" — already provided by ${where}` });
+		}
+	});
+	return { index, broken };
+}
+
+/** The published entry shape — the catalog's, and what `include` is shown. */
+function entryOf({ name, description, dir, path, userInvocable }) {
+	return { name, description, dir, path, userInvocable };
+}
+
 /** 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 })),
+		entries: index.map(entryOf),
 		broken: broken.map(({ dir, reason }) => ({ dir, reason })),
 		body(name) {
 			const skill = index.find((s) => s.name === name);

package/index.d.ts

@@ -16,20 +16,35 @@ type SkillsExtension = KisoExtension & { readonly skills?: number; readonly cata
 /** 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 SkillsCatalogEntry {
+	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;
+}
+
 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;
-	}[];
+	readonly entries: readonly SkillsCatalogEntry[];
 	/** 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>;
+/** For a host; the CLI passes none, and omitting both keeps the default scan. */
+export interface SkillsExtensionOptions {
+	/** Directories to scan, in order. Given → replaces the default
+	 *  (KISO_SKILLS_DIR, else $KISO_HOME/skills); the env var is not read.
+	 *  A name found twice resolves to the first occurrence (root order,
+	 *  then directory order); later ones are reported in `broken`. */
+	readonly roots?: readonly string[];
+	/** false → the skill is absent from the model's index, from `read_skill`,
+	 *  from the catalog and from the count, which are all built from one
+	 *  filtered list. Runs after duplicates resolve; `broken` is not filtered. */
+	readonly include?: (entry: SkillsCatalogEntry) => boolean;
+}
+
+declare const createSkillsExtension: (options?: SkillsExtensionOptions) => SkillsExtension | Promise<SkillsExtension>;
 export default createSkillsExtension;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-skills-ext",
-	"version": "0.44.0",
+	"version": "0.45.0",
 	"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.44.0",
+		"@vincemakes/kiso-core": "0.45.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"