writing-user-outputs_skill

Overview

This skill documents CLI output formatting standards for Worktrunk, focusing on user-facing messages, error handling, progress output, hints, warnings, and shell integration behavior. It captures conventions for stdout/stderr separation, symbol and color usage, heading case, and message consistency to produce predictable, script-friendly output. The guidance is written for developers producing Rust CLI output using the Worktrunk output helpers.

How this skill works

The output system centralizes formatting and shell integration so command code only calls output helpers and never branches on integration mode. Messages use styled helpers for success, progress, info, warning, hint, error, and prompt symbols and colors. Shell commands are written to a directive file when the WORKTRUNK_DIRECTIVE_FILE env var is set; otherwise the helpers are no-ops and the CLI prints informative warnings. stdout is reserved for pipeable data and shell code; stderr carries human-facing status and diagnostics.

When to use it

• When emitting primary command results intended for scripts, pipes, or eval (use stdout).
• When printing human-visible status, progress, hints, warnings, or errors (use stderr).
• When writing shell directives (cd, exec) that the shell wrapper should source after wt exits.
• When formatting messages that must acknowledge user-provided flags or options.
• When running hooks that execute in different paths and must show the run location.

Best practices

• Always call provided output helpers; do not branch command logic on shell integration state.
• Acknowledge explicit flags and options in messages by placing flag annotations adjacent to the noun they modify.
• Keep stdout machine-friendly (tables, JSON, shell code); keep stderr for human status and flush stderr before interactive prompts.
• Avoid pronouns and second-person phrasing; make hints and errors self-contained and referent-free.
• Use defined symbols with their native styling and close/reopen color contexts when embedding symbols within colored messages.
• Place warnings discovered during evaluation before the action message that follows from that evaluation.

Example use cases

• Create a worktree: print success to stderr and emit a cd directive to the directive file for shell integration.
• List worktrees: print a table or JSON to stdout for piping into jq or grep.
• Switch worktree: show progress and success messages on stderr and write no stdout data.
• Run hooks: use pre_hook_display_path or post_hook_display_path to show accurate hook run locations.
• Notify about retained branches: include the --no-delete-branch flag inline with the retention message.