Skip to content

fix(cli): improve guidelines for kilo agent create #9410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shssoichiro wants to merge 1 commit into from
Closed

fix(cli): improve guidelines for kilo agent create #9410

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 7 additions & 23 deletions packages/opencode/src/agent/generate.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,33 +33,17 @@ When a user describes what they want an agent to do, you will:

6 **Example agent descriptions**:

- in the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
- examples should be of the form:
- <example>
Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
user: "Please write a function that checks if a number is prime"
assistant: "Here is the relevant function: "
<function call omitted for brevity only for this example>
<commentary>
Since the user is greeting, use the Task tool to launch the greeting-responder agent to respond with a friendly joke.
</commentary>
assistant: "Now let me use the code-reviewer agent to review the code"
</example>
- <example>
Context: User is creating an agent to respond to the word "hello" with a friendly jok.
user: "Hello"
assistant: "I'm going to use the Task tool to launch the greeting-responder agent to respond with a friendly joke"
<commentary>
Since the user is greeting, use the greeting-responder agent to respond with a friendly joke.
</commentary>
</example>

@marius-kilocode marius-kilocode Apr 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Will this not break the formatting?

@shssoichiro shssoichiro Apr 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

No, the overall JSON formatting is still correct--this is defined in the section below ("Your output must be a valid JSON object...") The bulky examples XML is what we want to eliminate, because the agent is being guided to place these directly into the description field.

An example of the generated agent file before and after would make this clearer.

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

- If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
- NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
- in the 'whenToUse' field of the JSON object, you should include a description of when the agent should be used. Include the following:
- Trigger conditions, not just capability. Anthropic's guidance: "Reviews code for security issues before commits" routes better than "security expert." Name the situation, not the persona.
- When to invoke, phrased actively. "Use immediately after writing or modifying code," "Use when analyzing data," "Use proactively when encountering any issues." The phrase use proactively (or the community convention MUST BE USED for…) measurably increases auto-delegation — the main agent otherwise tends to do tasks itself rather than spawn.
- Input signal. What should be true when this fires? "errors, test failures, and unexpected behavior" / "after code changes" / "before commits" — these cue Claude to match against the current context, not just the verb.
- Avoid generic role nouns. "frontend-engineer," "security expert," "backend specialist" are weak signals because they overlap with almost any task.
- A good description will be 1-3 sentences on average, but there is no hard length limit. Ensure the description is complete enough to guide an agent on when to use it, but do not unnecessarily pad the length.

Your output must be a valid JSON object with exactly these fields:
{
"identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
"whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
"whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases.",
"systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
}

Expand Down
Loading