Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/user/providers-kiro.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,14 @@ 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, 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

Kiro asks before tool calls such as writes and commands, and T3 Code answers by the permission mode:
Expand Down
3 changes: 2 additions & 1 deletion packages/provider-kiro/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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:",
Expand Down
15 changes: 15 additions & 0 deletions packages/provider-kiro/src/server/driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -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,
Expand Down Expand Up @@ -82,6 +85,8 @@ export const KiroDriver: ProviderDriver<KiroSettings, KiroDriverEnv> = {
}) {
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,
Expand Down Expand Up @@ -160,6 +165,16 @@ export const KiroDriver: ProviderDriver<KiroSettings, KiroDriverEnv> = {
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;
Expand Down
92 changes: 92 additions & 0 deletions packages/provider-kiro/src/server/skills.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
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 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 })
.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(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");
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: "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[2]?.path, path.join(workspaceRoot, "shared", "SKILL.md"));
assert.isTrue(skills.every((entry) => entry.enabled));

// 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,
environment: { HOME: home, KIRO_HOME: kiroHome },
});
assert.deepEqual(
relocated.map(({ name, scope }) => ({ name, scope })),
[
{ name: "relocated-cloud", scope: "user" },
{ name: "relocated", scope: "user" },
{ name: "parent", scope: "project" },
],
);
}).pipe(Effect.provide(NodeServices.layer)),
);
});
104 changes: 104 additions & 0 deletions packages/provider-kiro/src/server/skills.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
/**
* 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<ReadonlyArray<ServerProviderSkill>, 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<string> => []));
const skills: Array<ServerProviderSkill> = [];
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: 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;
readonly environment: NodeJS.ProcessEnv;
}): Effect.fn.Return<ReadonlyArray<ServerProviderSkill>, never, FileSystem.FileSystem | Path.Path> {
const path = yield* Path.Path;
const home =
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<string, ServerProviderSkill>();
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) {
for (const skill of yield* readSkillsRoot(path.join(kiroFolder, "skills"), scope)) {
skills.set(skill.name, skill);
}
}
return [...skills.values()];
});
3 changes: 3 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading