Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

kitaru-investigation

Guide users from their own agent code or recorded traces through Kitaru setup, session import or recording, human review, an accepted behavior, a versioned cohort, and evaluator selection, then hand one bounded change to the replay-experiment skill. Use when a user wants to connect or inspect an existing agent, import real traces, investigate a known bad or surprising session, discover recurring failure modes, learn the evidence-led review flow, resume an investigation, create a cohort from reviewed evidence, or author an evaluator for an accepted behavior. When a first-time user has no agent or evidence and wants a fast demonstration with the public returns-agent template, use the `kitaru-guided-tour` skill instead.

decodingai-magazine · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add decodingai-magazine/building-a-coding-agent-from-scratch-course --skill kitaru-investigation

About this skill


name: kitaru-investigation description: Guide users from their own agent code or recorded traces through Kitaru setup, session import or recording, human review, an accepted behavior, a versioned cohort, and evaluator selection, then hand one bounded change to the replay-experiment skill. Use when a user wants to connect or inspect an existing agent, import real traces, investigate a known bad or surprising session, discover recurring failure modes, learn the evidence-led review flow, resume an investigation, create a cohort from reviewed evidence, or author an evaluator for an accepted behavior. When a first-time user has no agent or evidence and wants a fast demonstration with the public returns-agent template, use the kitaru-guided-tour skill instead.

Kitaru investigation

Treat this skill as Kitaru's evidence-led front door for real agents and traces. Guide one continuous journey from the evidence the user has to a reviewed behavior and, when they want to test a change, the kitaru-replay-experiment skill.

Core contract

  • Treat the human as the judge. Select, summarize, organize, and compile evidence; never turn an agent suggestion into a human label.
  • Preserve durable Kitaru state. Re-read existing objects before creating replacements, and carry exact agent, session, investigation, investigation-session, annotation, cohort-version, evaluator, and evaluator-version identifiers forward.
  • Separate observed behavior from desired behavior. A trace records what happened, not what should have happened or whether the external outcome was correct.
  • Distinguish agent behavior, external dependency behavior, product purpose, and independent outcome evidence.
  • Use open observations before proposing a taxonomy. Deterministic signals may select sessions; they do not judge them.
  • Explain remote writes and paid or live execution before running them. Ask for one proportional confirmation at the point of action.
  • Prefer native Kitaru MCP operations when available. CLI-only operation is supported; use the structured CLI for local files, built-in wait behavior, or an operation MCP does not expose.
  • Run every Kitaru CLI command and SDK script with KITARU_ACTIVE_SKILL=kitaru-investigation set so the server attributes the resulting activity to this skill.
  • Start or restart a user-controlled worker with --concurrency 10. Use KITARU_WORKER_CONCURRENCY=10 only when the launch surface exposes worker settings through environment variables instead of CLI options.
  • Stop at a useful durable checkpoint when a required source, payload, permission, worker, product contract, or UI capability is unavailable.

Keep the experience light

  • Lead with the current state and one next useful action.
  • Use ordinary language for user decisions. Keep internal labels such as trace-first, cold-start, question keys, and selectors out of the lead.
  • Ask for one meaningful judgment at a time. Do not turn setup into a long questionnaire.
  • Prefer short prose during active review. Use a table only when the user must compare repeated fields or several candidates.
  • Summarize structured output instead of dumping JSON. Preserve exact IDs, versions, warnings, and missing evidence in a compact checkpoint.
  • Show which claims came from the repository, traces, user, or agent reasoning.

Orient a first-time user

When the user is new to Kitaru, explain this five-step method once:

  1. Observe: turn recorded traces into Kitaru sessions and inspect what happened.
  2. Judge: let a human record what should have happened beside the evidence.
  3. Define: express one accepted behavior as an evaluator over a reviewed cohort.
  4. Replay: run one changed agent against the same situations under an explicit tool policy.
  5. Compare: decide whether the bounded evidence improved, regressed, traded off, or remained inconclusive.

Installation, agent registration, recording, and trace import are setup for Observe, not extra stages the user must memorize. Show the current step and next action after the orientation rather than repeating the whole map.

When a first-time user has no agent or traces and wants to see why Kitaru is useful through the public template, continue with the kitaru-guided-tour skill. For a generic first run with the user's own evidence, ask one user-facing question before choosing the review size:

Do you want to learn the review flow on one run, debug a specific behavior, or explore several runs to discover recurring problems?

Use a structured question action when the host provides one. Infer the path without asking when the request already names a session, investigation, or accepted behavior.

An incomplete starter handoff takes precedence over this question. Give the short five-step orientation, ask only for a reachable checkout, and defer choosing a review path until the source is available.

Load references only when needed

  • Read references/investigation-method.md before mapping the agent, selecting sessions, conducting review, or synthesizing behaviors.
  • Read references/kitaru-operations.md before checking setup or calling Kitaru CLI or MCP operations. Verify the installed schemas when they differ from the reference.
  • Read references/starter-template.md when frontend context names the starter or the checkout contains the public template's stable root contents. Use its guarded, README-led demo route before generic setup or trace-source questions.
  • Read references/deterministic-evaluators.md after the user accepts one behavior and cohort, or when they directly request evaluator selection.
  • Read references/evaluator-authoring.md only after checking the installed catalog. Continue there when no installed
Read the complete source ↗