Skip to content

fix(kiro): user and project Kiro skills show in the / and $ menus - #36200

Open
ChristopherPHolder wants to merge 3 commits into
pingdotgg:mainfrom
ChristopherPHolder:fix/kiro-project-skills
Open

ChristopherPHolder wants to merge 3 commits into
pingdotgg:mainfrom
ChristopherPHolder:fix/kiro-project-skills

Conversation

@ChristopherPHolder

@ChristopherPHolder ChristopherPHolder commented Nov 13, 2026 •

Copy link
Copy Markdown

Problem

On a Kiro thread the / and $ menus list no Kiro skills (#31645). I hit this on T3 Code 0.1.9-nightly.20261111.4515 with kiro-cli 3.1.0, in a project with 54 skill folders in .kiro/skills and 2 in ~/.kiro/skills: $ shows "No skills found. Try / to browse provider commands." before and after the first message. Kiro reports its skills only to a running session, and the Kiro provider publishes none of them.

Change

  • packages/provider-kiro/src/server/skills.ts reads the folders Kiro loads skills from, with Kiro's own rules (below): ~/.kiro/skills (or $KIRO_HOME/skills), <cwd>/.kiro/skills, and Kiro's local copy of the account's cloud skills in ~/.kiro/cloud-cache/resolved/config/user/skills.
  • The Kiro driver answers snapshotForCwd with that list, the same way the fx and Cursor drivers do. The composer already asks for a folder's skills through it, so nothing changes in contracts or clients.
  • docs/user/providers-kiro.md gets a short Skills section.

Reading the folders means no Kiro session (and none of the user's MCP servers) starts for a menu, the skills show on a new thread before the first message, and a project's skills are listed only for threads in that folder.

Cloud skills were added in ded780b9bd after this report that an account's cloud skills were still missing. Kiro keeps them in the cache folder above and loads them from there. Two limits: the folder is where Kiro puts them, not a documented location, and the menu shows them as of Kiro's last sync on that machine, so an account that has never started a Kiro session there lists none.

Relation to #31700. That PR records the skills a session advertises and publishes them on the machine snapshot. It leaves project skills out by design, because that snapshot is shared by every project, and it lists ~/.kiro/skills only after a Kiro session has started on the server. This PR covers both cases, so it overlaps the listing part of #31700. I did not port its $name to /name rewrite: with kiro-cli 3.1.0 a message that starts with $db-migration already makes Kiro load the skill (see below).

Scope

Bug fix for #31645. My comment with the project-skills case: #31645 (comment)

Verification

Everything below ran on macOS with kiro-cli 3.1.0 signed in to a Kiro account, except the one result marked as another user's.

Real app, both commits. Web dev server on an empty database, the default Kiro instance, model claude-haiku-4.5, Full access. The project kiro-skills-demo has three valid skills and one without a description in .kiro/skills; plain-project has no .kiro folder; ~/.kiro/skills has two skills.

Check main (f313d0a) this branch (f17ac58)
$ on a new thread in kiro-skills-demo, no message sent "No skills found. Try / to browse provider commands." effect-ts, effect-v3-to-v4 (personal), api-review, db-migration, release-notes (project)
/ on the same new thread /model /model and /skill:<name> for the same 5
the skill without a description – not listed, as in Kiro
$ on a new thread in plain-project not run the 2 personal skills only
pick db-migration from $ as the first message and send it not run Kiro loads the project skill, and the reply has the word its SKILL.md asks for
$ on that thread after the turn "No skills found. …" the same 5 skills
/ on that thread after the turn /model, /side, /btw, /clear, /compact those, and /skill:<name> for the 5

On main, the last two rows were read on the thread the branch had created, after its turn had finished. I did not send a message on main.

Before After
$
/

The screenshots are from the first commit of this branch, "before" being the same build without the driver change. The menus in them are the ones in the table.

Kiro's rules. I started real kiro-cli acp --agent-engine=v3 --auth-method=cli sessions in probe folders and read the _meta.kiro.type: "skill" entries of available_commands_update:

Probe Kiro 3.1.0
<cwd>/.kiro/skills/<folder>/SKILL.md listed, origin: "workspace", root: <cwd>
~/.kiro/skills/<folder>/SKILL.md listed, origin: "user"
KIRO_HOME set user skills come from $KIRO_HOME/skills; ~/.kiro/skills is not read
.kiro/skills of a parent folder or the git root, with cwd below it not listed
nested .kiro/skills/group/<folder>/SKILL.md, a loose .md, .agents/skills, .claude/skills not listed
no front matter, no name, no description, empty description, invalid YAML not listed
name UpperCase, snake_name, dot.name, has space, -leading, trailing-, double--hyphen, 65 characters, 123 not listed
name of 64 characters, 1digit, folder name different from name, CRLF, extra keys, no closing ---, symlinked folder, symlinked SKILL.md, hidden folder listed
description of 1024 characters listed
description of 1025 characters not listed
> or ` ` block description
same name in ~/.kiro/skills and the project one entry: the project's, in the user skill's position
same name in two project folders the later folder wins
<kiro home>/cloud-cache/resolved/config/user/skills/<folder>/SKILL.md listed before the user skills, origin: "cloud", provenance.scope: "user"
same name in the cloud folder and in ~/.kiro/skills or the project one entry: the local one, in the cloud skill's position
cloud folder: invalid name, description of 1025 characters, nested folder not listed
skills under cloud-cache/resolved/config/organization, org, team, group, enterprise, account, workspace, project, global, shared, or directly under config, resolved or cloud-cache not listed

The scan against Kiro. I ran the new scan over the same folders and compared its output with what Kiro advertised there, entry by entry (name, description, origin, order):

  • the five probe folders: 27 entries, identical;
  • with KIRO_HOME set: identical;
  • a Kiro home with cloud, user and project skills, three of them under the same name in more than one place: 8 entries, identical;
  • the real project from my report: identical, 49 entries. Kiro loads 47 of its 54 skill folders; the other 7 have a description over 1024 characters (6) or invalid YAML (1), and the scan leaves the same 7 out. The scan took 32 ms.

My account has no cloud skills, so for the cloud rows I put SKILL.md files in the cache folder of a throwaway KIRO_HOME and started a real session against it. Another user's run, with real cloud skills. The author of that report then ran the scan from ded780b9bd on Linux with kiro-cli 3.3.0 and compared it with a real session's skill entries (their comment). This is their result, not mine:

Setup Kiro Scan Name, description, order
their real ~/.kiro 71 71 identical
a throwaway KIRO_HOME with only a copy of their cloud-cache 65, all origin: "cloud" 65 identical

All 65 of their cloud skills are under cloud-cache/resolved/config/user/skills, and none comes from an organization. They compared the scan's output and did not open the $ menu in a running build.

Test. packages/provider-kiro/src/server/skills.test.ts builds a home folder with user and cloud skills, a workspace with those cases, and a KIRO_HOME, and checks the lists and their order.

The real-app table above was run on f17ac58822 and not repeated for ded780b9bd, which only adds one more folder to the same list.

In vp run check:changed, format, lint, knip, typecheck and tests pass. Its "unused patches" step fails on my machine on an unmet unenv peer dependency in infra/relay, which this PR does not touch.

Not checked:

  • Windows, and kiro-cli versions other than 3.1.0 by me. The run above used 3.3.0 for the scan comparison only.
  • Cloud skills an organization assigns. Kiro's sync state names an organization layer; I don't know whether those skills land in the user folder or somewhere this scan does not read. The account in the run above has none.
  • The menus in a running build with real cloud skills. My account has none, and the run above compared the scan's output.
  • The mobile client. It reads the same per-folder skills as web, and nothing changed there.
  • A custom Kiro agent that limits its skill:// resources. In the V3 engine, switching a session to an agent with "resources": [] sent no new command list, so I could not see a per-agent difference to follow.

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 pingdotgg#31645
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T15:09:54.056202Z 540555f PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions github-actions Bot added vouch:unvouched Author is not yet trusted in the VOUCHED list. size:L 100-499 changed lines (additions + deletions). labels Nov 13, 2026
@macroscopeapp

macroscopeapp Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Approvability

Verdict: Approved at 540555f

Macroscope's review found this PR approvable — Kiro's / and $ menus now list existing user and project skills using read-only, workspace-scoped discovery. The change does not automatically run skills or alter permissions or default selections.

You can add or adjust custom eligibility rules. Learn more.

@juliusmarminge juliusmarminge added the takeover:in-progress A takeover lead is working on this PR label Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The Kiro provider discovers and validates user and workspace skills. When Kiro is enabled, it adds discovered skills to the working-directory snapshot.

Changes: Kiro skill discovery

Layer / File(s) Summary
Skill discovery and validation
packages/provider-kiro/src/server/skills.ts, packages/provider-kiro/src/server/skills.test.ts, packages/provider-kiro/package.json, docs/user/providers-kiro.md
The provider reads cloud-cache, user, and workspace skill folders. It validates SKILL.md front matter and applies precedence to duplicate names. Tests check discovery and filtering. The documentation describes the sources, required fields, and precedence.
Working-directory snapshot integration
packages/provider-kiro/src/server/driver.ts
KiroDriver provides filesystem and path services to discovery. When Kiro is enabled, it adds discovered skills to the snapshot; otherwise, it returns the existing snapshot.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant KiroDriver
  participant discoverKiroSkills
  participant FileSystem
  KiroDriver->>discoverKiroSkills: cwd, environment, filesystem, and path services
  discoverKiroSkills->>FileSystem: read skill roots and SKILL.md files
  FileSystem-->>discoverKiroSkills: folder entries and file contents
  discoverKiroSkills-->>KiroDriver: discovered skills
  KiroDriver->>KiroDriver: add skills to enabled snapshot
Loading

Possibly related PRs

  • pingdotgg/t3code#31700: Uses Kiro available_commands_update data to add skills, while this change discovers skills from Kiro folders.

Suggested labels: bugfix

Suggested reviewers: juliusmarminge

Merge Risk: Minimal · up to ded78

This change adds user and project Kiro skills to the composer menus. It reads skill files and skips unreadable or invalid ones. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: Kiro user and project skills now appear in the / and $ composer menus. It uses the conventional commit form with a fix(kiro) scope, and the changeset adds skill discov…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description follows the repository template closely. It has Problem, Change, Scope, and Verification sections. The Problem section gives the symptom (empty / and $ menus on Kiro threads), the envi…
Full details: Title check

Explanation

The title names the main change: Kiro user and project skills now appear in the / and $ composer menus. It uses the conventional commit form with a fix(kiro) scope, and the changeset adds skill discovery for those menus through snapshotForCwd. The title is specific and matches the objectives.

Full details: Description check

Explanation

The description follows the repository template closely. It has Problem, Change, Scope, and Verification sections. The Problem section gives the symptom (empty / and $ menus on Kiro threads), the environment (T3 Code build, kiro-cli 3.1.0, macOS), and the linked issue. The Change section explains the driver and scan behavior and why no contract or client change is needed. The Scope section links issue #31645 and explains the bug-fix scope. The Verification section gives a real-app table, probe results for Kiro's skill rules, a scan-versus-Kiro comparison, a test file reference, and a list of unchecked items. It also names the model and harness that did the work, as the template asks for agent use. The reported cloud-skill comparison was run by another user and is labeled as such. Minor gaps: the description is long, and the template's conventional-commit title is not shown in the provided text. Those gaps are not critical.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between f17ac58 and ded780b.

Files selected for processing: 3

  • docs/user/providers-kiro.md
  • packages/provider-kiro/src/server/skills.test.ts
  • packages/provider-kiro/src/server/skills.ts
Files skipped from review as they are similar to previous changes: 1

  • docs/user/providers-kiro.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@juliusmarminge

Copy link
Copy Markdown
Member

The automated pipeline stopped on this pull request and will not merge it:

the fix is written and reviewed, but proving it needs something no worker has:

  • Permanent blocker: a signed-in Kiro account or KIRO_API_KEY is required to execute the supplied reproduction, especially sending a real message; neither was available in this unattended environment.
  • User and project skills in the $ and / menus before the first message, persistence after a message, and project isolation remain unverified on both commits.

It stays open for a person to finish or close.

@juliusmarminge juliusmarminge added takeover:blocked Takeover blocked; reason in the PR body and removed takeover:in-progress A takeover lead is working on this PR labels Nov 13, 2026
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.
@ChristopherPHolder

Copy link
Copy Markdown
Author

I ran these with a signed-in Kiro account (kiro-cli 3.1.0) and put the results in the description, on f313d0a6cb (main) and f17ac58822 (this branch):

  • Before the first message: on a new thread, $ and / list the personal and project skills on the branch; main shows "No skills found."
  • Real message: I picked a project skill from $ as the first message; Kiro loaded it and answered with the word the skill asks for.
  • After a message: the same skills are still listed on that thread.
  • Project isolation: a new thread in a project without .kiro lists only the personal skills.

One limit: I did not send a message on main; I read its "after a message" rows on the thread the branch had created.

Since the first review I also pushed f17ac58822, which reads user skills from KIRO_HOME when it is set.

I use Kiro daily and have a signed-in account, so I can run whatever would help get this in: exact reproduction steps you give me, a screen recording of the flow, the raw ACP traffic, or the same checks on another kiro-cli version. Tell me what you need and I'll post the output here.

@Nichokas

Copy link
Copy Markdown

+1. I hit #31645 with kiro-cli 3.3.0 on Linux, signed in with a Kiro API key, and ran some checks that may help this land.

Cloud skills are missing. Kiro also advertises the account's cloud skills, with _meta.kiro.type: "skill" and origin: "cloud". It caches them in ~/.kiro/cloud-cache/resolved/config/user/skills/<name>/SKILL.md when a session starts. In my case that was 65 skills, including the ones I actually use (/poteto-mode, /poteto-help). I ran this branch's discoverKiroSkills against that Kiro home, and it returned only the one project skill, so $ still doesn't show the skills I see in Kiro CLI. Reading that folder after ~/.kiro/skills, so local skills win, fixed it on my branch: Nichokas@8317589df. The folder is a cache path I observed, not a documented location, so you may prefer another source for these.

$name needs no rewrite, as you found. In three fresh kiro-cli acp --agent-engine=v3 sessions, $demo-skill beta loaded the skill (a Load skill: demo-skill tool call) and got the reply its SKILL.md asks for, the same as /demo-skill beta. The skill's description said it was never relevant, so the model didn't pick it up on its own. So the $ to / rewrite in #31700 isn't needed on current Kiro.

End to end in T3. On a similar disk-scan branch, a real Kiro thread started with $demo-skill gamma replied DEMO-SKILL-RAN gamma, and the $ menu listed the skills before the first message.

Kiro also loads the account's cloud skills, from its own copy in
<kiro home>/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.
@ChristopherPHolder

Copy link
Copy Markdown
Author

Thanks, that was a real gap. Added in ded780b: the scan now reads <kiro home>/cloud-cache/resolved/config/user/skills first, so a skill in ~/.kiro/skills or the project replaces a cloud skill of the same name, as in Kiro's list.

My account has no cloud skills, so I checked it with SKILL.md files I put in that folder of a throwaway KIRO_HOME. kiro-cli 3.1.0 lists them first with origin: "cloud", a local skill of the same name wins, and the scan returns the same 8 entries in the same order as Kiro. The description has the details.

Could you run this branch against your 65 and say whether $ now matches what Kiro CLI shows you? Two things I can't see from here: whether any of your cloud skills come from an organization rather than your own user, and whether all of them sit under config/user/skills.

@Nichokas

Copy link
Copy Markdown

Note

🤖 Claude Opus 5.5 responding on behalf of @Nichokas

ded780b matches Kiro on my machine (Linux, kiro-cli 3.3.0). I ran discoverKiroSkills from the branch on an empty folder and compared it with the skill entries of a real kiro-cli acp --agent-engine=v3 --auth-method=cli session in the same folder:

Setup Kiro Scan Name, description, order
My real ~/.kiro 71 71 identical
Throwaway KIRO_HOME with only a copy of my cloud-cache 65, all origin: "cloud" 65 identical

All 65 cloud skills also exist in ~/.kiro/skills, so with my real home the local copies win and Kiro reports all 71 as origin: "user", as you described.

Your two questions:

  • Organization: none of mine come from one. cloud-cache/resolved/config/state.json has a single layer, scope: "user", and all 184 synced files are source: "user".
  • Folder: all 65 are under cloud-cache/resolved/config/user/skills. Kiro also keeps a copy of the same 65 in cloud-cache/user/config/skills (older mtime), but the scan reads resolved, and that gave Kiro's exact list.

Not checked: the $ menu itself in a running build. I compared the scan's output, which the driver publishes unchanged.

@Nichokas

Nichokas commented Nov 15, 2026 •

Copy link
Copy Markdown

Note

🤖 Claude Opus 5.5 responding on behalf of @Nichokas

I ran the unverified checks from the pipeline's comment in a running build of ded780b9bd: web dev server, Linux, kiro-cli 3.3.0, signed in to a Kiro account with 65 cloud skills (also present in ~/.kiro/skills).

Check Result
$ on a new Kiro thread, no message sent lists my personal skills (1)
first message $setup-pstack Kiro shows "Loaded skill: setup-pstack" and reads the skill's references/runtimes.md (2)
$ on that thread after the turn same skills still listed
/ on that thread after the turn /skill:<name> entries for the same skills (3)
new thread in a project with .kiro/skills/demo-project-skill/SKILL.md demo-project-skill listed as "Project Skill", after the personal ones (4)
new thread in a project without .kiro, $demo demo-project-skill not listed; personal skills only (5)

Not checked: main side by side in this run, Windows, and organization-assigned cloud skills (my account has none).

Screenshots

1. $ on a new thread, before the first message

$ menu on a new Kiro thread listing personal skills

2. First message $setup-pstack: Kiro loads the skill

Turn showing Loaded skill: setup-pstack

3. /skill on the same thread after the turn

/skill entries after the turn

4. Project with .kiro/skills: demo-project-skill as Project Skill

demo-project-skill listed as Project Skill

5. Project without .kiro: $demo does not list the project skill

$demo in a project without .kiro shows only personal skills

@Nichokas

Nichokas commented Nov 15, 2026 •

Copy link
Copy Markdown

@juliusmarminge the pipeline stopped here because nobody had a signed-in Kiro account. I ran those checks above, including a real message and project isolation. Is that enough to unblock it, or is something else missing?

If this moves forward, I can test the implementation on a paid Kiro account (Kiro Pro, Linux, kiro-cli 3.3.0): check the values in Usage -> Limits against kiro-cli /usage, and check what happens on a CLI version without the method.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:L 100-499 changed lines (additions + deletions). takeover:blocked Takeover blocked; reason in the PR body vouch:unvouched Author is not yet trusted in the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants