Skip to content

feat(skills): load builtin dev skills everywhere, follow relocations - #16822

Merged
bolichen97 merged 1 commit into
mainfrom
skills/global-builtin-skills
Oct 4, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
skills/global-builtin-skills

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

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-tests and dev-fleet's pod-e2e carry repo_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-pr finds nothing. Separately, #16740 renamed kirocrew-dev/prepare-pr; an agent spec that maps the old skill:// 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

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 $name loads and the catalog: the maintainer wants these skills to trigger like any other skill. The deleted test_pod_e2e_declares_a_repo_scope pinned 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-pr loads nothing today, so a moved builtin skill is now followed: on every agent-config rebuild, any ~/ or absolute skill:// entry that names a relocated skill's old SKILL.md is 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-refactor does 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.md frontmatters (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 in src/kiro_crew/agent.py; the sweep in skills.py; docs in agent-spec-fields.md and memory-skills-hooks.md.

Backwards compatibility

Compatible: removing repo_scope only 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_so
Reader: 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; TestMigrateRelocatedSkillUris
Reader: kiro-cli agent spec loader -- chat|subagent|cron -- reads the rewritten resources list; only skill:// strings change, order kept
Reader: src/kiro_crew/skills.py:_ensure_builtin_skills -- release -- an unchanged installed kirocrew-codebase-refactor is parked, a user-edited one stays; test_a_dropped_nested_builtin_is_retired_beside_itself
Reader: 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 carries repo_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_disposed and test_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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested a review from a team as a code owner October 4, 2026 19:01
@bolichen97
bolichen97 requested a review from buluoray October 4, 2026 19:01
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 4, 2026
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 510fcad2cd123e655cf347ca8ede84e09b8c12bb — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Global triggers reach everyone who installs the package, not just maintainers. Removing -repo_scope: src/kiro_crew from skills in the public package makes their triggers match in unrelated projects. The broadest are prepare-pr's open pr, commit and push, fix ci, … enable auto-merge, writing-tests' write a test, add a test and pod-e2e's e2e test, … end to end. The model then gets Kiro Crew's auto-merge and push loop in someone else's repo, held back only by "Kiro Crew repo only". Builtin skills: load globally, rewrite relocated skill:// mappings, drop codebase-refactor #16807 is cited as the decision, but nothing under docs/decisions/ records it, so a later reviewer can't tell it was chosen on purpose.
    Clears when: a docs/decisions/ entry records that trigger matching is global for all installs, or triggers stay scoped while $name loads and the catalog go global.
  • Enrolled agents keep the stale path, with no notice. migrate_relocated_skill_uris skips any spec where get_capabilities(...) is not None ("left for a re-save in Capabilities"). Those agents still map kirocrew-dev/prepare-pr and load nothing, with no warning. That is the "lose the PR skill with no notice" harm the PR says it fixes.
    Clears when: a skipped enrolled spec that still maps a relocated URI logs a warning or shows a crew-page notice telling the user to re-save.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 4, 2026
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ human override accepted

@bolichen97 overrode this lane for 510fcad2cd123e655cf347ca8ede84e09b8c12bb via /ai-review override (this commit only).

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 4, 2026
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 510fcad2cd123e655cf347ca8ede84e09b8c12bb — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 510fcad

Verdict parsed from the review's SHA-scoped output markers for commit 510fcad2cd123e655cf347ca8ede84e09b8c12bb.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 510fcad2cd123e655cf347ca8ede84e09b8c12bb: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the skills/global-builtin-skills branch from 39e5a4e to 7a9b566 Compare October 4, 2026 19:09
@bolichen97

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 7a9b566655bfe4909fb03a4e2c730551f5fcf6fc.

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.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 4, 2026
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 510fcad2cd123e655cf347ca8ede84e09b8c12bb and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 510fcad

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 510fcad2cd123e655cf347ca8ede84e09b8c12bb: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

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 7a9b566655bfe4909fb03a4e2c730551f5fcf6fc manually from the Actions tab.

@bolichen97
bolichen97 force-pushed the skills/global-builtin-skills branch from 7a9b566 to 1f75f1b Compare October 4, 2026 19:32
@bolichen97

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 1f75f1b79c4249324ed19eec83cfcbac862f12ba.

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.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

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 1f75f1b79c4249324ed19eec83cfcbac862f12ba manually from the Actions tab.

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
@bolichen97
bolichen97 force-pushed the skills/global-builtin-skills branch from 1f75f1b to 510fcad Compare October 4, 2026 19:58
@bolichen97

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 510fcad2cd123e655cf347ca8ede84e09b8c12bb.

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.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 4, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 4, 2026 20:34

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 and test/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_hotspots and audit_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.py and memory-skills-hooks.md were 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_SKILLS map joined under skills_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 old SKILL.md. Relative and wildcard URIs return None.
  • No loop. No value in the map is also a key, so one pass is final. The function is also idempotent: test_is_idempotent passes.
  • Writes stay inside the agents dir. Only ~/.kiro/agents/*.json files are rewritten, each gated by _spec_path_is_safe (:2490). The read happens under agents_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).
  • 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-e2e stays hidden while dev-fleet is disabled.
  • I found no rule in security.md or governance.md that names repo_scope as 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 Path can never equal an absolute key.
  • Leaf-only link check: the family guard at :2306 already covers that case.

The touched test files pass at this head: 408 passed.

Non-blocking follow-ups

  1. 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 like commit and push, fix ci and enable auto-merge. Please reword the docstring to match the new policy.
  2. 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.
  3. 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.
  4. Untested guard. _spec_path_is_safe in migrate_relocated_skill_uris has no dedicated test. Add a symlinked-spec case to TestMigrateRelocatedSkillUris.

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.

@bolichen97
bolichen97 merged commit a0786b7 into main Oct 4, 2026
98 of 99 checks passed
@bolichen97
bolichen97 deleted the skills/global-builtin-skills branch October 4, 2026 21:02
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Builtin skills: load globally, rewrite relocated skill:// mappings, drop codebase-refactor

2 participants