Repository navigation
feat(skills): load builtin dev skills everywhere, follow relocations - #16822
Conversation
Design Review (Opus 5.5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Kiro Crew's own developer skills now trigger in every user's projects, and the only guard is a line in each description that the model has to obey. Watch
[DESIGN-REVIEWED] 510fcad Description read[DESCRIPTION-READ] 81f4df05991ab5170176eeb9a5202fdce046425d36eb70a0a69f613dd6f2b6db That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ human override accepted@bolichen97 overrode this lane for |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
39e5a4e to
7a9b566
Compare
|
/ai-review override first-principles 7a9b566: agent: records maintainer @bolichen97's explicit decisions for #16807: builtin Kiro Crew dev skills drop repo_scope and load in every session, relying on their "Kiro Crew repo only" descriptions (no in-skill target-repo check); agent specs mapping a relocated builtin skill are rewritten to the new path; kirocrew-codebase-refactor leaves the main repo. |
Human judgment recorded@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: First Principles Review. Re-run the lane's latest workflow run for |
7a9b566 to
1f75f1b
Compare
|
/ai-review override first-principles 1f75f1b: agent: records maintainer @bolichen97's explicit decisions for #16807: builtin Kiro Crew dev skills drop repo_scope and load in every session, relying on their "Kiro Crew repo only" descriptions (no in-skill target-repo check); agent specs mapping a relocated builtin skill are rewritten to the new path; kirocrew-codebase-refactor leaves the main repo. |
Human judgment recorded@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: First Principles Review. Re-run the lane's latest workflow run for |
The Kiro Crew developer skills (kirocrew-prepare-pr, kirocrew-worktree-dev, writing-tests, dashboard-template and dev-fleet's pod-e2e) no longer carry repo_scope, so they load in every session like any other skill. Each description says it is for the Kiro Crew repo only, and the model decides. An agent spec that maps a relocated builtin skill's old skill:// path is rewritten to the new path on every agent-config rebuild, so the kirocrew-dev/prepare-pr rename needs no manual re-map. kirocrew-codebase-refactor leaves the package; an unchanged installed copy is retired by the sync. The stale sweep and the relocation quarantine both refuse to act through a linked directory anywhere on a nested name's path. Closes #16807
1f75f1b to
510fcad
Compare
|
/ai-review override first-principles 510fcad: agent: records maintainer @bolichen97's explicit decisions for #16807: builtin Kiro Crew dev skills drop repo_scope and load in every session, relying on their "Kiro Crew repo only" descriptions (no in-skill target-repo check); agent specs mapping a relocated builtin skill are rewritten to the new path; kirocrew-codebase-refactor leaves the main repo. |
Human judgment recorded@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
buluoray
left a comment
There was a problem hiding this comment.
Review of 510fcad2cd — approve
I found no defects in the code logic. All three areas I was asked to check hold up at this head. CI shows 90 success, 8 skipped and 0 failed on 510fcad2cd.
1. The −2801 lines: deleted, not moved
- The only skill removed is
kirocrew-dev/kirocrew-codebase-refactor: its SKILL.md, eight references, three scripts andtest/test_kirocrew_refactor_helpers.py. It is not in_RELOCATED_SKILLS(src/kiro_crew/skills.py:1189-1195) and gets no new path. That is right for a drop. - Nothing points at it any more. I ran a repo-wide grep for
codebase-refactor,refactor_limits,scan_refactor_hotspotsandaudit_refactor_overlap. Every hit is the new stale-list entry, the spec sentence that describes the drop, or its tests. No AGENTS.md link, builtin_skills reference or doc points at a removed file.scripts/check_builtin_skill_scope.pyandmemory-skills-hooks.mdwere updated in this same commit. - Installs that already have the skill retire it through the stale sweep (
skills.py:2294-2301). The parked slot sits next to the skill in its family directory (stale.with_name(...),:2316). - The other five SKILL.md edits only change frontmatter and descriptions. Each file still exists at its old path.
2. Relocation following: no escape, no loop
- Targets are fixed. The old and new paths come only from the hard-coded
_RELOCATED_SKILLSmap joined underskills_dir()(agent.py:2474-2478). Spec content never decides where a URI ends up._relocated_skill_uri(agent.py:2426) only rewrites a URI whose normalized path exactly equals a known oldSKILL.md. Relative and wildcard URIs returnNone. - No loop. No value in the map is also a key, so one pass is final. The function is also idempotent:
test_is_idempotentpasses. - Writes stay inside the agents dir. Only
~/.kiro/agents/*.jsonfiles are rewritten, each gated by_spec_path_is_safe(:2490). The read happens underagents_spec_lock(:2486). - Fail-closed paths:
- If the lock can't be taken (
OSError), nothing is written and it retries on the next rebuild. - If capabilities can't be read, the spec is treated as enrolled and skipped (
:2503). - If a write fails, it logs a warning and the spec is left as it was.
- It only acts once the new file exists and the old one is gone (
:2477).
- If the lock can't be taken (
- Link handling. The sweep and the quarantine now refuse to act through a link anywhere on a nested name's path (
_linked_component,skills.py:2107; call sites:2306,:2320,:2363). These paths are also fail-closed: they skip and log.
3. "Everywhere": does not widen what a governed agent can see
repo_scope is a relevance gate that runs on top of visibility. It is not the visibility control.
- Every gate site first iterates
_iter_visible(project_dir), which applies mapping scope (e.g.skills.py:5369,skill_runtime/delivery.py:634). - The spec says mapping scope, disabled apps and project consent are each re-evaluated independently (
memory-skills-hooks.md~4108, ~4323). - So an agent restricted to certain mapped skills still sees only those, and
pod-e2estays hidden while dev-fleet is disabled. - I found no rule in
security.mdorgovernance.mdthat namesrepo_scopeas a boundary. The change only widens which projects an already-visible skill loads in.
Mutation probes (one test file each, reverted afterwards)
| Guard removed | Test that fails |
|---|---|
| enrolled-member skip | TestMigrateRelocatedSkillUris::test_leaves_an_enrolled_members_saved_generation_alone |
not old_md.exists() |
test_leaves_a_mapping_whose_old_skill_still_loads |
| family-link guard in the stale sweep | TestStaleCleanupGuard::test_a_parked_slot_behind_a_linked_family_is_not_disposed |
| codebase-refactor stale entry | test_a_dropped_nested_builtin_is_retired_beside_itself |
_spec_path_is_safe in the new migration |
none (follow-up 4) |
Two mutants are equivalent:
- Accepting relative URIs: a relative
Pathcan never equal an absolute key. - Leaf-only link check: the family guard at
:2306already covers that case.
The touched test files pass at this head: 408 passed.
Non-blocking follow-ups
- Stale docstring.
SkillLoader._repo_scope_satisfied(skills.py:3707-3729) still says "destructive repo-dev instructions must be mechanically contained" and that prose "depends on probabilistic LLM obedience". After this PR, no builtin skill uses that gate. The most destructive one, prepare-pr's push and auto-merge loop, now relies on its description alone, even though its triggers include generic phrases likecommit and push,fix ciandenable auto-merge. Please reword the docstring to match the new policy. - No decision record. #16807 records this as a maintainer decision, but no
docs/decisions/entry exists. The Design Review lane flags the same gap. One would make the global-trigger choice discoverable later. - Silent skip for enrolled agents. An enrolled member whose spec maps a relocated URI is skipped without notice (
agent.py:2504). It keeps loading nothing, which is the "no notice" harm this PR sets out to fix. A warning log, or a crew-page notice telling the user to re-save, would close it. Design Review raises this too. - Untested guard.
_spec_path_is_safeinmigrate_relocated_skill_urishas no dedicated test. Add a symlinked-spec case toTestMigrateRelocatedSkillUris.
Bot lanes
- Opus and GPT: no blocking findings.
- Design Review: CONCERNS, advisory. Its two points are follow-ups 2 and 3 above; I checked both in source.
- First Principles: overridden for this head by @bolichen97, who is the author and a repo admin. The override records the #16807 decision. I checked the code side of that decision myself (the visibility gate is unchanged) and found it sound.
Problem / Motivation
Goal: Kiro Crew's own developer skills load in any folder, and an agent mapped to a moved skill keeps it.
Today
kirocrew-prepare-pr,kirocrew-worktree-dev,writing-testsand dev-fleet'spod-e2ecarryrepo_scope: src/kiro_crew. They load only when the session's project is a Kiro Crew checkout, so a Kiro Crew PR written from another folder gets none of them, and$kirocrew-prepare-prfinds nothing. Separately, #16740 renamedkirocrew-dev/prepare-pr; an agent spec that maps the oldskill://path silently loads nothing after the upgrade.Why it matters
Maintainers write Kiro Crew PRs from many folders and lose the PR loop, the worktree rules and the test rules there. Agents mapped to the old path lose the PR skill with no notice, and the only fix today is a manual re-map on the crew page.
Not a goal
repo_scopeitself for lessons or for user-authored skills..kiro/agentsin a project) or markdown agent specs.What changed (motivation → approach → change)
The scope gate keeps these skills out of the folders maintainers actually work in, so it goes. Each Kiro Crew-only description now says "Kiro Crew repo only" (or keeps its existing statement), and the model decides from it. Trigger matching goes global on purpose too, not only
$nameloads and the catalog: the maintainer wants these skills to trigger like any other skill. The deletedtest_pod_e2e_declares_a_repo_scopepinned the opposite rule, so its replacement pins this one. This is the maintainer's decision recorded in #16807; there is no RFC.An agent mapped to the renamed
kirocrew-dev/prepare-prloads nothing today, so a moved builtin skill is now followed: on every agent-config rebuild, any~/or absoluteskill://entry that names a relocated skill's oldSKILL.mdis rewritten to the new path, in place, under the same agent-spec lock every template writer holds. It acts only once the new file exists and the old one is gone, and it skips an enrolled member's spec, a saved capability generation that a re-save in Capabilities updates.kirocrew-codebase-refactordoes not belong in the main repo, so it leaves the package, and an unchanged installed copy is retired so it stops loading. It is the first nested name the stale sweep handles, so the sweep and the relocation quarantine now refuse to act through a linked directory anywhere on that path: moving a file through a user's link would touch their files outside the skills home.Where: the five
SKILL.mdfrontmatters (builtin_skills/kirocrew-dev/kirocrew-prepare-pr/SKILL.md,kirocrew-worktree-dev/SKILL.md,writing-tests/SKILL.md,dashboard-template/SKILL.md,apps/builtins/dev_fleet/skills/pod-e2e/SKILL.md); the rewrite insrc/kiro_crew/agent.py; the sweep inskills.py; docs inagent-spec-fields.mdandmemory-skills-hooks.md.Backwards compatibility
Compatible: removing
repo_scopeonly widens where the skills load, and the mapping rewrite points an entry at a file that exists.Reader: src/kiro_crew/skills.py:_repo_scope_satisfied -- chat|subagent|cron -- the five skills have no scope, so the gate admits them everywhere;
test_kiro_crew_dev_skills_load_globally_and_say_soReader: src/kiro_crew/dashboard/handlers/_shared.py:skill_key_for_uri -- crew page -- the rewritten URI names the installed
SKILL.md, so it inverts to the catalog key;TestMigrateRelocatedSkillUrisReader: kiro-cli agent spec loader -- chat|subagent|cron -- reads the rewritten
resourceslist; onlyskill://strings change, order keptReader: src/kiro_crew/skills.py:_ensure_builtin_skills -- release -- an unchanged installed
kirocrew-codebase-refactoris parked, a user-edited one stays;test_a_dropped_nested_builtin_is_retired_beside_itselfReader: scripts/check_builtin_skill_scope.py, docs/system-specs/modules/memory-skills-hooks.md -- release -- no longer name the dropped skill
Reader: test/test_kirocrew_refactor_helpers.py -- release -- deleted with the scripts it tested
Tests
test_kiro_crew_dev_skills_load_globally_and_say_so: none of the five skills carriesrepo_scope, and each description states it is for Kiro Crew.TestMigrateRelocatedSkillUris: rewrites~/and absolute forms in place, drops a duplicate, is idempotent, leaves a still-loadable old path and relative or wildcard entries alone.test_leaves_an_enrolled_members_saved_generation_alone: an enrolled member's spec, or one whose intent cannot be read, is never rewritten.test_a_dropped_nested_builtin_is_retired_beside_itself: fails on main, passes here.test_a_dropped_nested_builtin_behind_a_linked_family_is_untouched: a linked family directory is never moved through.test_a_parked_slot_behind_a_linked_family_is_not_disposedandtest_reads_and_writes_inside_the_spec_lock: both fail on the first local-review commit and pass here.test_agent_spec_hardened_reads.py: the label ratchet lists the new reader.Manual verification
N/A — the rewrite and the sweep are file operations covered end to end by the unit tests above.
Related Issues
Closes #16807
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)