[knihit]

Description

Kiro agents rarely load a matching skill unless the user tells them to. An agent's own prompt had no "when" for its skills, and the agent couldn't see which skills existed until it called the deferred skills tool. This PR has synth append a short "Your skills" block to every Kiro agent's prompt. The block holds a use-matching-skills rule, how to load a skill, and the agent's own declared skills. The skills MCP server stays the load path.

Kiro only. Claude Code already lists every skill and loads it with its native Skill tool, with no MCP server involved, and the benchmark showed no measured gain from a rule there (6 against 5 of 12). So Claude Code agent output is unchanged.

Stacked on the fix/skill-name-filter PR, which makes each Kiro agent's skills server serve only that agent's skills. Review and merge that one first.

Synth (cli/konductor-rs/src/cli/synth/):

• New skill_index.rs builds the block. kiro_cli_v2.rs and kiro_cli_v3.rs append it in their transform() loop.
• One - <name>: <trigger> line per dependencies.skills.skillNames entry, in declared order. The trigger is the description's first Use ... or MUST USE sentence, kept whole, led by the first sentence when that is a different one, so the line keeps what the skill does. The first sentence is trimmed on a word boundary to fit 160 characters, or dropped when less than 40 would be left. With no Use sentence the trigger is the first sentence alone, capped at 160. Em and en dashes become hyphens.
• The load line says to use get_skill on the konductor-skills MCP server, calling tool_load first if the tool is deferred. Both names come from the new cli/skills_server.rs, which install now shares, so renaming the server or tool can't leave the prompt pointing at a stale name.
• The rule: before a non-trivial task, check whether a listed skill covers it, load at most one or two, follow their steps and output format, and skip trivial tasks. Workspace ws-* skills also count and are read from .kiro/skills/<name>/SKILL.md, matching core rule 10.
• A skill whose trigger starts with MUST USE for every (today only constraints) is left out of the list, with no line about it. It claims every task, which would contradict the one-or-two rule. A task-specific MUST USE for <task> trigger, such as git-merge, stays in the list. Synth prints a warning to stderr when any skill other than constraints matches the rule, so a new one isn't dropped silently.
• Orchestrators (konductor*) also get a sentence telling them to route skill-matching work to the owning specialist, and to load from the list only for their own orchestration work.
• render_agent_file, the agent file structs, claude.rs, the agent specs and context/ are unchanged. Nothing is written to ~/.kiro/skills or .kiro/skills.

Tests:

• Unit tests in skill_index.rs cover trigger extraction (including the first sentence leading a later Use sentence, checked against the real backend-review description), sentence splitting (AGENTS.md stays whole), the cap, dash conversion, declared order, the orchestrator paragraph, the one-or-two wording, leaving constraints out, keeping git-merge, and the every-task warning.
• kiro_block_names_the_installed_server_and_tool checks the block names the shared server and tool constants and the ws-* path, and grants_are_built_from_the_shared_server_and_tool_names in mcp_server.rs checks the install grants are built from the same constants.
• New tests/synth_skill_index_e2e.rs runs a real synth. For every agent, the Kiro v2 and v3 index names equal the source spec's skillNames minus constraints, in declared order, constraints is not named, and no Claude Code agent file carries a skill block. An agent with no skills must have no block, rather than failing the test.

Docs:

• docs/user-guide/reference.md ("Behaviour worth knowing" under synth output) and cli/README.md (synth) now note the generated ## Your skills block and that skills whose description starts "MUST USE for every" (today only constraints) are left out. The published HTML guide doesn't carry this sentence, so it is unchanged.

Skills (descriptions, all harnesses):

• progress-tracking: the Use sentence listed modes, not tasks, so its index line gave a task nothing to match. It now says "Use when validating a feature plan, tracking its progress, or checking requirements against code."
• adversarial-code-review-pass-security, -integrity, -schema: the second sentence now reads "Use only when the adversarial-code-review coordinator spawns it", so the index doesn't present them as standalone reviews.
• These descriptions also reach Claude Code, whose native skill matching reads them, and they changed after the benchmark ran.

Changelog:

• One bullet under [Unreleased] / Changed. No VERSION change.

Kiro block size per agent (from make synth, identical on v2 and v3; the Skills column counts declared skills, and constraints is not listed):

Agent	Skills	Block (B)
k-architect	38	6,841
k-developer	27	5,128
k-product-manager	16	3,183
konductor	13	2,798
k-tpm	14	2,720
k-quality-assurance	13	2,502
konductor-mux-orchestrator	11	2,339
konductor-cmux-orchestrator	11	2,338
k-researcher	9	1,901
k-browser	5	1,133
k-media-analyzer	2	677

k-developer's block is about 1,250 tokens. For comparison, #113 adds about 17 KB to every agent.

Type of Change

• CLI (cli/) change: Rust
• Context / system prompt update (generated at synth for Kiro. No source prompt or context file changed.)

Testing

• npm test: 119 of 136 pass. The same 17 fail on main (claude-code-agent-runner, generate-agent-files, run-claude-subset), and this PR touches none of their code. Not rerun after the review fixes, which change no JS.

• cd cli && make test: 1809 passed, 0 failed. telemetry_hook_scoping, which this PR doesn't touch, failed once under parallel load on macOS and passed with --test-threads=1 and on a full rerun.

• mcp make test: 325 passed. make -C cli lint passes. make -C mcp lint reports cargo fmt diffs in five skill-lookup test files; main reports the same five under the same toolchain. python3 -m pytest -q tests/: 222 passed. make guide-check: the one failure (config in WITHDRAWN_COMMANDS) is also on main. make test-skills-sh 10 passed, 1 skipped (existing exclude), make claude-plugin-check pass, make test-py 222 passed, kiro-power-check passed.

• Synth output: dist/claude is byte-identical to main for every agent (diff -r clean).

• Smoke tested: make build && make synth, then installed with --from . --no-telemetry into a scratch HOME and target. The kiro-cli v3 k-developer prompt ends with the block, and its 27 index names equal its --skill-name-filter names. .kiro/skills holds only sop-* entries, and nothing was written under HOME's .kiro.

• Benchmark run against main. The Kiro block in that build matched this branch before the review fixes, which changed it (re-bench below). The bench numbers are from 3662fe8. The later commits (the ws-* sentence and first-sentence-led triggers) grow the 11 v2 blocks from 25,804 to 31,560 bytes (+22%; k-architect 5,464 to 6,841, k-developer 4,064 to 5,128) and have not been benchmarked. That build also had a names-only Claude Code line, which this branch dropped after the run.

  Setup: 4 tasks that each match one agent's skill (T1 backend review, T2 user stories, T3 threat model, T4 test coverage; direct, plus T1 and T2 through konductor) and a no-skill control. 2 reps per cell, project-scope install with --no-telemetry, isolated HOME per run, scored from session logs rather than agent self-reports.

  Harness	Variant	n	Loaded a skill	Right skill	Followed skill format	Control loaded a skill
  Kiro CLI v3	main	12	4	3	0	0/2
  Kiro CLI v3	this branch	12	9	9	4	0/2
  Claude Code	main	12	5	5	4	0/2
  Claude Code	names-only line (dropped)	12	6	6	4	0/2

  On Kiro the right skill loaded unprompted in 9 of 12 runs, against 3 of 12 on main. 8 of those 9 went tool_load then get_skill on the agent's own skill, and the skills server was reported unavailable in 0 of 28 Kiro runs. Mean Kiro cost per task run rose from 2.10 to 2.56 credits. On Claude Code the line gave 6 against 5 of 12, within run-to-run noise, which is why this PR leaves Claude Code alone.

  Caveats:

  • Each task cell has only 2 runs, and main varied by about 1 run in 12 between two benchmark passes.
  • Two Kiro loads came from an agent reading a project-scope SKILL.md directly (one on main, one here). Without them, Kiro is 2/12 against 8/12.
  • T1 is still weak: backend-review loaded in 1 of 8 direct runs, and konductor answered T1 itself instead of delegating in all 8 orchestrated runs.

  Follow-up comparison on Kiro CLI v3, same harness, model and scoring: X is this branch before the review fixes (constraints listed as a normal line), Y is the final head (constraints left out). Task runs only (T1 to T4, T1 and T2 also through konductor). Reps 1 and 2 are the passes above; reps 3 and 4 ran X and Y interleaved run by run, and a 60-credit cap stopped them after 21 runs (rep 4 lacks T3 for Y and T4 for both).

  Variant	Runs	Right skill	Loaded constraints	Mean credits per run
  main (reps 1 and 2)	12	3	n/a	2.10
  X, reps 3 and 4	11	6	3	2.55
  Y, reps 3 and 4	10	6	0	2.58
  X, pooled	23	15	6	2.56
  Y, pooled	22	13	0	2.68

  Task, pooled right skill	X	Y
  T1 direct	1/4	0/4
  T1 orchestrated	0/4	0/4
  T2 direct	4/4	4/4
  T2 orchestrated	3/4	3/4
  T3 direct	4/4	3/3
  T4 direct	3/3	3/3

  The X vs Y gap is within noise. Across the 22 matched X/Y runs, only 3 disagree: 2 favour X (T1 direct rep 2, T2 orchestrated rep 1) and 1 favours Y (T2 orchestrated rep 4). The one difference that holds is constraints: X loads it in 6 of 23 runs and Y never does. Cost per run is the same within noise; the mean gap comes from the T2 orchestrated runs, which swing between 1 and 7.5 credits. No run loaded a wrong skill, and no run reported the skills server unavailable. T1 stays the weak task on both.

• All three new .rs files start with // SPDX-License-Identifier: Apache-2.0

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own changes
• I have commented my code where necessary
• I have made corresponding changes to the documentation (CHANGELOG, docs/user-guide/reference.md and cli/README.md)
• My changes generate no new warnings: make -C cli lint (cargo clippy -- -D warnings, cargo fmt --check) passes
• I have added or updated tests that prove my change works

Agents Affected

Every agent's Kiro CLI v2 and v3 prompt gains the block. Claude Code agents are unchanged.

• konductor
• konductor-mux-orchestrator
• konductor-cmux-orchestrator
• k-developer
• k-architect
• k-researcher
• k-product-manager
• k-quality-assurance
• k-tpm
• k-browser
• k-media-analyzer

Notes for Reviewers

• The rule paragraphs live in skill_index.rs because they name the MCP server and tool through the same constants the installer uses, so the prompt and the install can't disagree. Moving them to a template would bring that drift back. They are Kiro-only and say less than core rule 10 and the routing rules, which still govern.

• Own commits: the first adds the block on all three harnesses, and the second drops the Claude Code part after the benchmark. After review, a merge brings in the fix/skill-name-filter review fixes, then four commits address this PR's review: shared server names (with a first take on constraints), the docs, keeping git-merge listed, and leaving constraints out of the index. Four more follow from the next round: is_orchestrator moves into synth/model.rs, the rule names ws-* skills, triggers lead with the first sentence, and the every-task rule is stated in the docs with a synth warning. Two more keep the Use sentence whole when it fits and name the expected every-task skill as a constant. Review the combined diff.

• Overlap with fix(orchestrator): tighten the direct-work rules #114: the only textual conflict is CHANGELOG.md [Unreleased]. fix(orchestrator): tighten the direct-work rules #114 adds "delegate a step you lack the skill for" to the routing rules, and the orchestrator sentence here says the same thing for skill-matching work. Re-read the combined wording once both land.

• Overlap with feat(synth): deny subagent spawning for specialist agents #124: feat(synth): deny subagent spawning for specialist agents #124 adds model::is_specialist (prefix k-) and changes kiro_cli_v3.rs's use super::model::CanonicalModel; to use super::model::{is_specialist, CanonicalModel};. This PR adds model::is_orchestrator (prefix konductor) to synth/model.rs, after the CanonicalModel struct, so the two predicates sit in one file. A trial git merge-tree against feat(synth): deny subagent spawning for specialist agents #124 merges model.rs and CHANGELOG.md cleanly. The one conflict is in kiro_cli_v3.rs's imports: this PR adds use super::parse_canonical::skill_names_from_dependencies; right below the line feat(synth): deny subagent spawning for specialist agents #124 rewrites, and the fix is to keep both. Once both land, is_orchestrator could be defined as the complement of is_specialist, unless a third role prefix is expected.

• constraints is not listed. Its NEVER DO and writing rules reach agents through the core rules, and the remaining rules are a known gap tracked separately. On main Kiro agents don't see it listed either. A first fix listed it on an always-apply line outside the one-or-two budget, and agents then loaded it in 6 of 10 runs. Listed as a normal line, it loaded in 6 of 23 runs with no measurable effect on the right-skill rate (15/23 against 13/22 without it, within noise), so this PR leaves it out.

• If the MCP server binary is missing at install, the server is skipped with a warning while the prompt still names get_skill. That install was already broken before this change.