Rtk Output Design

RTK Output Design

Use this skill to make CLI, skill, hook, and script output useful to an agent without flooding its context. Treat output as a contract: preserve the signal needed for the next action, make compression explicit, and keep raw detail available on demand.

Core Contract

Design every command around this shape:

status: success | partial | failure
summary: one sentence with the important result
stats: counts, durations, paths, bytes, token estimates, or changed totals
items: only the highest-value errors, warnings, changed files, matches, or rows
omitted: what was hidden and why, with counts when possible
next_actions: concrete commands or fixes when the result is not done
provenance: command, mode, input scope, and source paths when relevant

For human output, render this shape as compact sections. For automation, expose it as stable JSON.

Output Modes

Provide these modes when the tool has non-trivial output:

Preserve upstream exit codes unless the wrapper itself fails. If filtering fails, prefer raw output plus a short filter warning over hiding command results.

Filtering Strategy

Choose the cheapest strategy that preserves the next useful action:

Never compress away:

• Non-zero status, panic, exception, traceback, failed assertion, or stderr.
• File paths, line numbers, command names, versions, config locations, or IDs needed for the next command.
• Security, permission, data-loss, migration, or destructive-action warnings.
• The fact that output was omitted.

Default Text Template

Use this layout for CLI output that an agent will read:

<STATUS>: <one-sentence summary>

Stats:
- <count or metric>
- <duration or scope>

Findings:
- <file:line or id> <message>
- <group> <count> occurrences, example: <short sample>

Omitted:
- <count> low-signal lines hidden; use --raw or --verbose for details

Next:
- <single best next command or action>

Omit empty sections. Keep the default output small enough to scan in one screen; for broad commands, prefer the top 10 to 20 actionable items plus counts.

JSON Schema

For --json, use one object with stable keys:

{
  "status": "success",
  "summary": "3 files changed, no failures",
  "command": {
    "argv": ["tool", "check"],
    "cwd": "/repo",
    "exit_code": 0,
    "duration_ms": 1234
  },
  "stats": {
    "files": 3,
    "warnings": 0,
    "errors": 0,
    "omitted_lines": 248
  },
  "items": [
    {
      "kind": "change",
      "path": "src/main.rs",
      "line": 42,
      "message": "updated parser"
    }
  ],
  "omitted": [
    {
      "kind": "progress",
      "count": 248,
      "reason": "progress and success lines hidden"
    }
  ],
  "next_actions": ["run cargo test"],
  "meta": {
    "schema": "rtk-output-design.v1",
    "raw_available": true
  }
}

Rules:

• Keep keys stable across versions. Add optional keys instead of renaming.
• Use arrays for repeated data even when there is one item.
• Use null only when absence is meaningful; otherwise omit optional keys.
• Keep raw multiline blobs out of JSON unless explicitly requested.
• Include schema when downstream agents or tests may depend on the shape.

Skill And Hook Output

For skills, prompts, and hooks:

• Start with the decision or result, then evidence. Do not make agents infer the status from a long transcript.
• Include the minimum procedure needed to reproduce or continue.
• Put large references behind paths or commands the agent can open only when needed.
• For generated plans or reports, label each item with status, owner/scope, and verification evidence.
• For hook rewrites or suggestions, show the original command, rewritten command, and reason in one compact block.

Example hook message:

RTK: rewrite suggested
original: pytest -q
rewrite:  rtk pytest -q
reason:   filter passing tests; preserve failures and exit code

CLI Development Checklist

Before shipping a CLI, skill helper, or script:

1. Define the default text output and --json schema before implementation.
2. Decide which filtering strategy applies to each verbose command path.
3. Preserve exit codes and stderr semantics.
4. Add --raw or an equivalent debug path for compressed output.
5. Make omissions visible with counts and reasons.
6. Sort findings by actionability: failures, unsafe warnings, changed paths, grouped summaries, then success details.
7. Bound examples and list lengths. Include totals so truncation is honest.
8. Test success, partial, failure, no-match, huge-output, and parser-error cases.
9. Snapshot JSON shape or validate it with schema assertions.
10. Verify the output from an agent perspective: can the next command be chosen without asking for the raw transcript?

Anti-Patterns

• Printing banners, progress bars, spinners, dependency trees, or full passing test logs by default.
• Hiding non-zero exits behind a friendly summary.
• Returning prose-only output for data another script must parse.
• Emitting invalid JSON with comments, log prefixes, or trailing text.
• Showing raw files or diffs when counts plus changed paths would answer the question.
• Compressing output without saying what was omitted.
• Creating a skill that explains usage at length but does not define the output contract agents should follow.

Acceptance Test

A tool follows this guide when an agent can answer these questions from default output alone:

• Did it succeed, partially succeed, or fail?
• What changed or what was found?
• What exact file, line, command, or ID matters next?
• What was hidden, and how can raw detail be recovered?
• What command or edit should happen next?

If any answer requires scanning raw logs, redesign the output or add a focused summary path.