From 540555f290499527a7cf669d66ca609eff1f15c7 Mon Sep 17 00:00:00 2001 From: ChristopherPHolder Date: Fri, 13 Nov 2026 16:03:21 +0100 Subject: [PATCH 1/3] fix(kiro): user and project Kiro skills show in the / and $ menus Kiro reports skills only to a running session, so the composer menus on a Kiro thread never listed any. The Kiro provider now reads the folders Kiro loads skills from, `~/.kiro/skills` and the thread folder's `.kiro/skills`, when the composer asks for a folder's skills. Skills show before the first message, and project skills are scoped to their own folder. The scan follows what kiro-cli 3.1.0 advertises for the same folders: one level deep, front matter with a valid `name` and a `description`, and a project skill replacing a same-named user skill. Refs #31645 --- docs/user/providers-kiro.md | 7 ++ packages/provider-kiro/package.json | 3 +- packages/provider-kiro/src/server/driver.ts | 15 +++ .../provider-kiro/src/server/skills.test.ts | 69 ++++++++++++ packages/provider-kiro/src/server/skills.ts | 100 ++++++++++++++++++ pnpm-lock.yaml | 3 + 6 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 packages/provider-kiro/src/server/skills.test.ts create mode 100644 packages/provider-kiro/src/server/skills.ts diff --git a/docs/user/providers-kiro.md b/docs/user/providers-kiro.md index 6b94ca14f2e5..ffd0990b9561 100644 --- a/docs/user/providers-kiro.md +++ b/docs/user/providers-kiro.md @@ -38,6 +38,13 @@ not listed yet. Refresh the Kiro provider after adding or removing an agent. The thread's model still applies when an agent sets its own `model`. An agent that was removed leaves the thread on Kiro's current agent. +## Skills + +The `/` and `$` menus list the Kiro skills in `~/.kiro/skills` and in `.kiro/skills` of the folder +the thread runs in. As in Kiro, a parent folder's `.kiro/skills` is not read, a skill needs a valid +`name` and a `description` in its `SKILL.md`, and a project skill replaces a `~/.kiro/skills` skill +of the same name. + ## Permission Modes Kiro asks before tool calls such as writes and commands, and T3 Code answers by the permission mode: diff --git a/packages/provider-kiro/package.json b/packages/provider-kiro/package.json index be2781eacfce..2c24dd80abee 100644 --- a/packages/provider-kiro/package.json +++ b/packages/provider-kiro/package.json @@ -29,7 +29,8 @@ "@t3tools/provider-acp": "workspace:*", "@t3tools/provider-core": "workspace:*", "@t3tools/shared": "workspace:*", - "effect": "catalog:" + "effect": "catalog:", + "yaml": "catalog:" }, "devDependencies": { "@effect/platform-node": "catalog:", diff --git a/packages/provider-kiro/src/server/driver.ts b/packages/provider-kiro/src/server/driver.ts index 0a4e9b85fa28..bc822c65bf6e 100644 --- a/packages/provider-kiro/src/server/driver.ts +++ b/packages/provider-kiro/src/server/driver.ts @@ -3,6 +3,8 @@ import { KiroSettings } from "../settings.ts"; import * as HostProcess from "@t3tools/shared/HostProcess"; import * as SecureRandom from "effect/crypto/SecureRandom"; import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Path from "effect/Path"; import * as Schema from "effect/Schema"; import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"; @@ -25,6 +27,7 @@ import { } from "@t3tools/provider-core/server/snapshotSettings"; import type { ProviderTextGeneration } from "@t3tools/provider-core/server/textGeneration"; import { type KiroAdapterV2DriverEnv, makeKiroAdapterV2Driver } from "./adapter.ts"; +import { discoverKiroSkills } from "./skills.ts"; import { buildInitialKiroProviderSnapshot, checkKiroProviderStatus, @@ -82,6 +85,8 @@ export const KiroDriver: ProviderDriver = { }) { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const crypto = yield* SecureRandom.SecureRandom; + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; const processEnv = yield* mergeProviderInstanceEnvironment( environment, yield* HostProcess.Environment, @@ -160,6 +165,16 @@ export const KiroDriver: ProviderDriver = { accentColor, enabled, snapshot, + snapshotForCwd: (cwd) => + !effectiveConfig.enabled + ? snapshot.getSnapshot + : Effect.all([ + snapshot.getSnapshot, + discoverKiroSkills({ cwd, environment: processEnv }).pipe( + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + ), + ]).pipe(Effect.map(([machineSnapshot, skills]) => ({ ...machineSnapshot, skills }))), orchestrationAdapter, textGeneration: unsupportedTextGeneration, } satisfies ProviderInstance; diff --git a/packages/provider-kiro/src/server/skills.test.ts b/packages/provider-kiro/src/server/skills.test.ts new file mode 100644 index 000000000000..21d13e677dad --- /dev/null +++ b/packages/provider-kiro/src/server/skills.test.ts @@ -0,0 +1,69 @@ +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { assert, describe, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Path from "effect/Path"; + +import { discoverKiroSkills } from "./skills.ts"; + +describe("discoverKiroSkills", () => { + // Each case is what a kiro-cli 3.1.0 session advertised in + // `available_commands_update` for the same folders. + it.effect("lists the user and workspace skills a Kiro session loads", () => + Effect.gen(function* () { + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-kiro-skills-home-" }); + const repo = path.join(home, "repo"); + const workspace = path.join(repo, "packages", "app"); + const userRoot = path.join(home, ".kiro", "skills"); + const workspaceRoot = path.join(workspace, ".kiro", "skills"); + const write = (root: string, folder: string, contents: string) => + fileSystem + .makeDirectory(path.join(root, folder), { recursive: true }) + .pipe( + Effect.andThen( + fileSystem.writeFileString(path.join(root, folder, "SKILL.md"), contents), + ), + ); + const skill = (name: string, description: string) => + `---\nname: ${name}\ndescription: ${description}\n---\n\nBody.\n`; + + yield* write(userRoot, "shared", skill("shared", "user copy")); + yield* write(userRoot, "user-only", skill("user-only", "from the home folder")); + yield* write(workspaceRoot, "block", "---\nname: block\ndescription: >\n one\n two\n---\n"); + yield* write(workspaceRoot, "crlf", "---\r\nname: crlf\r\ndescription: windows\r\n---\r\n"); + yield* write(workspaceRoot, "folder-a", skill("renamed", "named by its front matter")); + yield* write(workspaceRoot, "open", "---\nname: open\ndescription: no closing fence\n"); + yield* write(workspaceRoot, "shared", skill("shared", "workspace copy")); + // Kiro loads none of these. + yield* write(workspaceRoot, "bad-yaml", "---\nname: bad-yaml\ndescription: [unclosed\n---\n"); + yield* write(workspaceRoot, "capitals", skill("Capitals", "invalid name")); + yield* write(workspaceRoot, "long-name", skill("a".repeat(65), "name over 64 characters")); + yield* write(workspaceRoot, "no-description", "---\nname: no-description\n---\n"); + yield* write(workspaceRoot, "no-frontmatter", "Just a body.\n"); + yield* write(workspaceRoot, "numeric", skill("123", "YAML reads the name as a number")); + yield* write(workspaceRoot, "snake", skill("snake_case", "invalid name")); + yield* write(workspaceRoot, "wordy", skill("wordy", "x".repeat(1_025))); + yield* write(path.join(workspaceRoot, "group"), "nested", skill("nested", "too deep")); + yield* write(path.join(repo, ".kiro", "skills"), "parent", skill("parent", "above cwd")); + yield* fileSystem.writeFileString(path.join(workspaceRoot, "loose.md"), skill("loose", "x")); + + const skills = yield* discoverKiroSkills({ cwd: workspace, environment: { HOME: home } }); + + assert.deepEqual( + skills.map(({ name, description, scope }) => ({ name, description, scope })), + [ + { name: "shared", description: "workspace copy", scope: "project" }, + { name: "user-only", description: "from the home folder", scope: "user" }, + { name: "block", description: "one two", scope: "project" }, + { name: "crlf", description: "windows", scope: "project" }, + { name: "renamed", description: "named by its front matter", scope: "project" }, + { name: "open", description: "no closing fence", scope: "project" }, + ], + ); + assert.equal(skills[0]?.path, path.join(workspaceRoot, "shared", "SKILL.md")); + assert.isTrue(skills.every((entry) => entry.enabled)); + }).pipe(Effect.provide(NodeServices.layer)), + ); +}); diff --git a/packages/provider-kiro/src/server/skills.ts b/packages/provider-kiro/src/server/skills.ts new file mode 100644 index 000000000000..f0da16805f0d --- /dev/null +++ b/packages/provider-kiro/src/server/skills.ts @@ -0,0 +1,100 @@ +/** + * Lists Kiro skills for the `/` and `$` menus from the SKILL.md folders Kiro + * reads. Kiro reports skills only to a running session, and a session starts + * the user's MCP servers, so none is opened for a composer menu. + * + * @module provider-kiro/server/skills + */ +import type { ServerProviderSkill } from "@t3tools/contracts"; +import * as HostProcess from "@t3tools/shared/HostProcess"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Option from "effect/Option"; +import * as Path from "effect/Path"; +import * as Schema from "effect/Schema"; +import { parse as parseYamlDocument } from "yaml"; + +const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; +const MAX_NAME_LENGTH = 64; +const MAX_DESCRIPTION_LENGTH = 1_024; + +const decodeSkillFrontmatter = Schema.decodeUnknownOption( + Schema.Struct({ name: Schema.String, description: Schema.String }), +); + +/** + * Reads SKILL.md as Kiro CLI 3.1.0 does: the file opens with `---`, the YAML + * runs to the closing `---` or the end of the file, and a skill without a + * valid `name` and a `description` is not loaded. + */ +function parseKiroSkill( + contents: string, +): { readonly name: string; readonly description: string } | undefined { + const opening = /^---[ \t]*\r?\n/.exec(contents); + if (opening === null) return undefined; + const rest = contents.slice(opening[0].length); + const closing = /^---[ \t]*\r?$/m.exec(rest); + let parsed: unknown; + try { + parsed = parseYamlDocument(closing === null ? rest : rest.slice(0, closing.index)); + } catch { + return undefined; + } + const frontmatter = Option.getOrUndefined(decodeSkillFrontmatter(parsed)); + if (frontmatter === undefined) return undefined; + const { name } = frontmatter; + // Kiro shows a block description on one line. + const description = frontmatter.description.replace(/\s+/g, " ").trim(); + return SKILL_NAME.test(name) && + name.length <= MAX_NAME_LENGTH && + description.length > 0 && + description.length <= MAX_DESCRIPTION_LENGTH + ? { name, description } + : undefined; +} + +const readSkillsRoot = Effect.fn("KiroSkills.readSkillsRoot")(function* ( + directory: string, + scope: "user" | "project", +): Effect.fn.Return, never, FileSystem.FileSystem | Path.Path> { + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + // A missing root, a stray file and an unreadable SKILL.md are all "no skill here". + const folders = yield* fileSystem + .readDirectory(directory) + .pipe(Effect.orElseSucceed((): Array => [])); + const skills: Array = []; + for (const folder of folders.toSorted()) { + const skillPath = path.join(directory, folder, "SKILL.md"); + const contents = yield* Effect.option(fileSystem.readFileString(skillPath)); + const skill = Option.isSome(contents) ? parseKiroSkill(contents.value) : undefined; + if (skill !== undefined) skills.push({ ...skill, path: skillPath, scope, enabled: true }); + } + return skills; +}); + +/** + * The skills a Kiro session in `cwd` loads: `~/.kiro/skills`, then the + * workspace's own `.kiro/skills` (Kiro reads no parent folder). A later + * skill replaces a same-named earlier one in its place, as in Kiro's list. + */ +export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (input: { + readonly cwd: string; + readonly environment: NodeJS.ProcessEnv; +}): Effect.fn.Return, never, FileSystem.FileSystem | Path.Path> { + const path = yield* Path.Path; + const home = + input.environment.HOME?.trim() || + input.environment.USERPROFILE?.trim() || + (yield* HostProcess.HomeDirectory); + const skills = new Map(); + for (const [base, scope] of [ + [home, "user"], + [input.cwd, "project"], + ] as const) { + for (const skill of yield* readSkillsRoot(path.join(base, ".kiro", "skills"), scope)) { + skills.set(skill.name, skill); + } + } + return [...skills.values()]; +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 744838ebefa9..319373bf9603 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1858,6 +1858,9 @@ importers: effect: specifier: 4.1.3 version: 4.1.3 + yaml: + specifier: ^2.9.0 + version: 2.9.0 devDependencies: '@effect/platform-node': specifier: 4.1.2 From f17ac588220f8fd33f13deecbe68fb46d9487675 Mon Sep 17 00:00:00 2001 From: ChristopherPHolder Date: Fri, 13 Nov 2026 16:26:21 +0100 Subject: [PATCH 2/3] fix(kiro): read user skills from KIRO_HOME when it is set With KIRO_HOME set, kiro-cli 3.1.0 lists the skills in $KIRO_HOME/skills and none from ~/.kiro/skills, so a Kiro instance with that variable showed the wrong user skills. --- packages/provider-kiro/src/server/skills.test.ts | 15 +++++++++++++++ packages/provider-kiro/src/server/skills.ts | 16 +++++++++------- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/packages/provider-kiro/src/server/skills.test.ts b/packages/provider-kiro/src/server/skills.test.ts index 21d13e677dad..b2b8ae399569 100644 --- a/packages/provider-kiro/src/server/skills.test.ts +++ b/packages/provider-kiro/src/server/skills.test.ts @@ -64,6 +64,21 @@ describe("discoverKiroSkills", () => { ); assert.equal(skills[0]?.path, path.join(workspaceRoot, "shared", "SKILL.md")); assert.isTrue(skills.every((entry) => entry.enabled)); + + // With KIRO_HOME set, Kiro reads `$KIRO_HOME/skills` and not `~/.kiro/skills`. + const kiroHome = path.join(home, "other-account"); + yield* write(path.join(kiroHome, "skills"), "relocated", skill("relocated", "in KIRO_HOME")); + const relocated = yield* discoverKiroSkills({ + cwd: repo, + environment: { HOME: home, KIRO_HOME: kiroHome }, + }); + assert.deepEqual( + relocated.map(({ name, scope }) => ({ name, scope })), + [ + { name: "relocated", scope: "user" }, + { name: "parent", scope: "project" }, + ], + ); }).pipe(Effect.provide(NodeServices.layer)), ); }); diff --git a/packages/provider-kiro/src/server/skills.ts b/packages/provider-kiro/src/server/skills.ts index f0da16805f0d..6c4d0da5a81a 100644 --- a/packages/provider-kiro/src/server/skills.ts +++ b/packages/provider-kiro/src/server/skills.ts @@ -74,9 +74,10 @@ const readSkillsRoot = Effect.fn("KiroSkills.readSkillsRoot")(function* ( }); /** - * The skills a Kiro session in `cwd` loads: `~/.kiro/skills`, then the - * workspace's own `.kiro/skills` (Kiro reads no parent folder). A later - * skill replaces a same-named earlier one in its place, as in Kiro's list. + * The skills a Kiro session in `cwd` loads: `~/.kiro/skills` (`KIRO_HOME` + * replaces `~/.kiro`), then the workspace's own `.kiro/skills` (Kiro reads no + * parent folder). A later skill replaces a same-named earlier one in its + * place, as in Kiro's list. */ export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (input: { readonly cwd: string; @@ -87,12 +88,13 @@ export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (inp input.environment.HOME?.trim() || input.environment.USERPROFILE?.trim() || (yield* HostProcess.HomeDirectory); + const kiroHome = input.environment.KIRO_HOME?.trim() || path.join(home, ".kiro"); const skills = new Map(); - for (const [base, scope] of [ - [home, "user"], - [input.cwd, "project"], + for (const [kiroFolder, scope] of [ + [kiroHome, "user"], + [path.join(input.cwd, ".kiro"), "project"], ] as const) { - for (const skill of yield* readSkillsRoot(path.join(base, ".kiro", "skills"), scope)) { + for (const skill of yield* readSkillsRoot(path.join(kiroFolder, "skills"), scope)) { skills.set(skill.name, skill); } } From ded780b9bd17d6cff145f2789c3e2b3fa019cc09 Mon Sep 17 00:00:00 2001 From: ChristopherPHolder Date: Sun, 15 Nov 2026 14:19:35 +0100 Subject: [PATCH 3/3] fix(kiro): list the account's cloud skills too Kiro also loads the account's cloud skills, from its own copy in /cloud-cache/resolved/config/user/skills. Read that folder first, so a skill in ~/.kiro/skills or the workspace replaces a cloud skill of the same name, as in Kiro's list. --- docs/user/providers-kiro.md | 7 ++++--- packages/provider-kiro/src/server/skills.test.ts | 14 +++++++++++--- packages/provider-kiro/src/server/skills.ts | 10 ++++++---- 3 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/user/providers-kiro.md b/docs/user/providers-kiro.md index ffd0990b9561..2b217688edbb 100644 --- a/docs/user/providers-kiro.md +++ b/docs/user/providers-kiro.md @@ -41,9 +41,10 @@ leaves the thread on Kiro's current agent. ## Skills The `/` and `$` menus list the Kiro skills in `~/.kiro/skills` and in `.kiro/skills` of the folder -the thread runs in. As in Kiro, a parent folder's `.kiro/skills` is not read, a skill needs a valid -`name` and a `description` in its `SKILL.md`, and a project skill replaces a `~/.kiro/skills` skill -of the same name. +the thread runs in, and your Kiro account's cloud skills as Kiro last synced them to this machine. +As in Kiro, a parent folder's `.kiro/skills` is not read, a skill needs a valid `name` and a +`description` in its `SKILL.md`, and a project skill replaces a `~/.kiro/skills` skill of the same +name, which replaces a cloud skill of the same name. ## Permission Modes diff --git a/packages/provider-kiro/src/server/skills.test.ts b/packages/provider-kiro/src/server/skills.test.ts index b2b8ae399569..870ec9c96dbc 100644 --- a/packages/provider-kiro/src/server/skills.test.ts +++ b/packages/provider-kiro/src/server/skills.test.ts @@ -18,6 +18,9 @@ describe("discoverKiroSkills", () => { const workspace = path.join(repo, "packages", "app"); const userRoot = path.join(home, ".kiro", "skills"); const workspaceRoot = path.join(workspace, ".kiro", "skills"); + const cloudSkills = (kiroHome: string) => + path.join(kiroHome, "cloud-cache", "resolved", "config", "user", "skills"); + const cloudRoot = cloudSkills(path.join(home, ".kiro")); const write = (root: string, folder: string, contents: string) => fileSystem .makeDirectory(path.join(root, folder), { recursive: true }) @@ -29,6 +32,8 @@ describe("discoverKiroSkills", () => { const skill = (name: string, description: string) => `---\nname: ${name}\ndescription: ${description}\n---\n\nBody.\n`; + yield* write(cloudRoot, "cloud-only", skill("cloud-only", "from the account")); + yield* write(cloudRoot, "user-only", skill("user-only", "cloud copy")); yield* write(userRoot, "shared", skill("shared", "user copy")); yield* write(userRoot, "user-only", skill("user-only", "from the home folder")); yield* write(workspaceRoot, "block", "---\nname: block\ndescription: >\n one\n two\n---\n"); @@ -54,19 +59,21 @@ describe("discoverKiroSkills", () => { assert.deepEqual( skills.map(({ name, description, scope }) => ({ name, description, scope })), [ - { name: "shared", description: "workspace copy", scope: "project" }, + { name: "cloud-only", description: "from the account", scope: "user" }, { name: "user-only", description: "from the home folder", scope: "user" }, + { name: "shared", description: "workspace copy", scope: "project" }, { name: "block", description: "one two", scope: "project" }, { name: "crlf", description: "windows", scope: "project" }, { name: "renamed", description: "named by its front matter", scope: "project" }, { name: "open", description: "no closing fence", scope: "project" }, ], ); - assert.equal(skills[0]?.path, path.join(workspaceRoot, "shared", "SKILL.md")); + assert.equal(skills[2]?.path, path.join(workspaceRoot, "shared", "SKILL.md")); assert.isTrue(skills.every((entry) => entry.enabled)); - // With KIRO_HOME set, Kiro reads `$KIRO_HOME/skills` and not `~/.kiro/skills`. + // With KIRO_HOME set, Kiro reads that folder and nothing under `~/.kiro`. const kiroHome = path.join(home, "other-account"); + yield* write(cloudSkills(kiroHome), "relocated-cloud", skill("relocated-cloud", "cloud")); yield* write(path.join(kiroHome, "skills"), "relocated", skill("relocated", "in KIRO_HOME")); const relocated = yield* discoverKiroSkills({ cwd: repo, @@ -75,6 +82,7 @@ describe("discoverKiroSkills", () => { assert.deepEqual( relocated.map(({ name, scope }) => ({ name, scope })), [ + { name: "relocated-cloud", scope: "user" }, { name: "relocated", scope: "user" }, { name: "parent", scope: "project" }, ], diff --git a/packages/provider-kiro/src/server/skills.ts b/packages/provider-kiro/src/server/skills.ts index 6c4d0da5a81a..736f5d01eb1f 100644 --- a/packages/provider-kiro/src/server/skills.ts +++ b/packages/provider-kiro/src/server/skills.ts @@ -74,10 +74,10 @@ const readSkillsRoot = Effect.fn("KiroSkills.readSkillsRoot")(function* ( }); /** - * The skills a Kiro session in `cwd` loads: `~/.kiro/skills` (`KIRO_HOME` - * replaces `~/.kiro`), then the workspace's own `.kiro/skills` (Kiro reads no - * parent folder). A later skill replaces a same-named earlier one in its - * place, as in Kiro's list. + * The skills a Kiro session in `cwd` loads: the account's cloud skills, then + * `~/.kiro/skills` (`KIRO_HOME` replaces `~/.kiro`), then the workspace's own + * `.kiro/skills` (Kiro reads no parent folder). A later skill replaces a + * same-named earlier one in its place, as in Kiro's list. */ export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (input: { readonly cwd: string; @@ -91,6 +91,8 @@ export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (inp const kiroHome = input.environment.KIRO_HOME?.trim() || path.join(home, ".kiro"); const skills = new Map(); for (const [kiroFolder, scope] of [ + // Kiro's own copy of the account's cloud skills, synced when a session starts. + [path.join(kiroHome, "cloud-cache", "resolved", "config", "user"), "user"], [kiroHome, "user"], [path.join(input.cwd, ".kiro"), "project"], ] as const) {