fix(cli): improve guidelines for kilo agent create

[shssoichiro]

Reopens #9410

Context

Currently the kilo agent create command generates extremely long agent descriptions. This is because the system prompt for the generate agent tells it to include multiple verbose examples of when the agent should be used. This is unnecessary and increases system context bloat without improving the parent agent's ability to choose a subagent.

Implementation

This change updates the system prompt to exclude the guidance about examples, and instead includes official guidance from Anthropic's documentation on best practices for agent descriptions.

Example Output

Before:

---
description: >-
  Use this agent when automated tests need to be executed and their results
  analyzed. This includes running unit tests, integration tests, end-to-end
  tests, or any test suite, then interpreting pass/fail outcomes, diagnosing
  failures, and providing actionable insights.


  <example>

  Context: The user has just finished implementing a new feature and wants to
  verify nothing is broken.

  user: "I just added the new authentication middleware. Can you make sure
  everything still works?"

  assistant: "I'll use the Task tool to launch the test-executor agent to run
  the test suite and analyze the results."

  <commentary>

  Since the user wants to verify their changes haven't broken anything, use the
  test-executor agent to run tests and analyze outcomes.

  </commentary>

  </example>


  <example>

  Context: The user is debugging a failing CI pipeline.

  user: "The CI is red but I can't tell which tests are actually failing."

  assistant: "Let me use the test-executor agent to run the tests locally and
  break down exactly what's failing and why."

  <commentary>

  The user needs test execution with detailed failure analysis, which is the
  test-executor agent's specialty.

  </commentary>

  </example>


  <example>

  Context: Proactive use after code changes.

  user: "I refactored the payment processing module to use the new API."

  assistant: "I've noted the refactoring. Now I'll use the test-executor agent
  to run the relevant tests and confirm the refactor didn't introduce
  regressions."

  <commentary>

  After significant code changes, proactively use the test-executor agent to
  validate correctness.

  </commentary>

  </example>
mode: subagent
---
You are an elite Test Execution and Analysis Specialist with deep expertise in...

After:

---
description: >-
  Use this agent when automated tests need to be executed and their results
  analyzed. This includes running unit tests, integration tests, end-to-end
  tests, or full test suites, as well as re-running failed tests and providing
  concise summaries of outcomes. The agent should be invoked after code changes
  that warrant verification, when explicitly asked to run tests, or proactively
  after implementing new features or fixes.
mode: subagent
---
You are an elite Test Execution Specialist with deep expertise in...

Get in Touch

ExpedientFalcon on Discord

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

The change replaces verbose XML <example> blocks in the agent generation prompt with concise, Anthropic-recommended guidance for writing whenToUse descriptions. This is a clean improvement that reduces generated context bloat and aligns agent description quality with best practices (trigger conditions, active invocation phrasing, input signals, avoiding generic role nouns).

The removed examples also contained a pre-existing content bug (a code-review example whose <commentary> incorrectly described it as a greeting response), so removing them is strictly an improvement.

No bugs, logic errors, resource leaks, or security concerns.

Files Reviewed (1 file)

• packages/opencode/src/agent/generate.txt

Fix these issues in Kilo Cloud

Previous Review Summary (commit 30f025c)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 30f025c)

Status: No Issues Found | Recommendation: Merge

The change replaces verbose XML <example> blocks in the agent generation prompt with concise, Anthropic-recommended guidance for writing whenToUse descriptions. This is a clean improvement that reduces generated context bloat and aligns agent description quality with best practices (trigger conditions, active invocation phrasing, input signals, avoiding generic role nouns).

The removed examples also contained a pre-existing content bug (a code-review example whose <commentary> incorrectly described it as a greeting response), so removing them is strictly an improvement.

No bugs, logic errors, resource leaks, or security concerns.

Files Reviewed (1 file)

• packages/opencode/src/agent/generate.txt

Fix these issues in Kilo Cloud

---

_{Reviewed by deepseek-v4-pro-20260423 · 355,101 tokens}

_{Review guidance: REVIEW.md from base branch main}

[markijbema]

This looks like a good improvement to me. Please allow us some time to discuss changes like this where we cant currently place kilocode change markers

[markijbema]

conclusion for now: we'd like to add markers to files like these, but accept that we'll have to fix merge conflicts more manually for now