writing-user-outputs
CLI output formatting standards for worktrunk. Use when writing user-facing messages, error handling, progress output, hints, warnings, or working with the output system.
79
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/writing-user-outputs/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid skill description that clearly communicates both what the skill does and when to use it, with good trigger term coverage. Its main weakness is that the 'what' portion describes categories of output rather than specific concrete actions (e.g., it says 'error handling' rather than specifying what formatting patterns or standards are applied). Overall it performs well for skill selection purposes.
Suggestions
Add more specific concrete actions to improve specificity, e.g., 'Defines color-coded error messages, spinner/progress indicators, structured hint blocks, and warning formatting for worktrunk CLI output.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (CLI output formatting for worktrunk) and lists several areas (user-facing messages, error handling, progress output, hints, warnings, output system), but these are categories rather than concrete actions like 'format error messages with color codes' or 'display progress bars'. | 2 / 3 |
Completeness | Clearly answers both what ('CLI output formatting standards for worktrunk') and when ('Use when writing user-facing messages, error handling, progress output, hints, warnings, or working with the output system') with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms that a user/developer would use: 'user-facing messages', 'error handling', 'progress output', 'hints', 'warnings', 'output system', 'CLI output', 'formatting'. These cover common variations well. | 3 / 3 |
Distinctiveness Conflict Risk | Scoped specifically to 'worktrunk' CLI output formatting, which is a clear niche. The combination of the specific project name and the output/formatting focus makes it unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and highly actionable reference for worktrunk's CLI output system, with excellent concrete examples and clear GOOD/BAD comparisons throughout. Its main weaknesses are its monolithic length (could benefit from splitting into sub-documents) and the lack of explicit step-by-step workflows with validation checkpoints for multi-step formatting tasks. The content is project-specific and valuable, though some sections could be more concise.
Suggestions
Split the document into a concise overview SKILL.md with links to separate reference files (e.g., SHELL_INTEGRATION.md, MESSAGE_FORMATTING.md, ERROR_FORMATTING.md, STYLING_REFERENCE.md) to improve progressive disclosure.
Add an explicit workflow/checklist for 'adding a new user-facing message' that sequences the decisions (choose message type → pick symbol → determine stdout/stderr → apply styling → add snapshot test) with validation steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is extensive and mostly relevant, but includes some sections that could be tightened—e.g., the Windows compatibility section, the detailed security explanation, and some repetitive examples showing both GOOD and BAD patterns where one would suffice. However, most content is project-specific knowledge Claude wouldn't have, which justifies its inclusion. | 2 / 3 |
Actionability | The skill provides highly concrete, executable Rust code examples throughout, specific function names with their modules, exact formatting patterns with GOOD/BAD comparisons, and precise API references (function signatures, symbol tables, style constants). Nearly every guideline is accompanied by copy-paste-ready code. | 3 / 3 |
Workflow Clarity | While individual patterns are clearly explained, the document lacks explicit sequenced workflows with validation checkpoints. The decision trees (e.g., warning placement, prompt types) are helpful, but for multi-step processes like error formatting or output sequencing, there are no explicit 'step 1, step 2, validate' flows. The document reads more as a reference than a workflow guide. | 2 / 3 |
Progressive Disclosure | The document is quite long and monolithic—it covers shell integration architecture, output formatting, styling, error handling, verbose output, path formatting, table alignment, and snapshot testing all in one file. While it has clear section headings, much of the detailed content (e.g., documentation examples, gutter formatting, verbose output patterns) could be split into separate reference files with links from the main skill. Some references to source files exist but are inline rather than structured as navigation. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
72%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 8 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (976 lines); consider splitting into references/ and linking | Warning |
metadata_version | 'metadata.version' is missing | Warning |
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 8 / 11 Passed | |
- Repository
- max-sixty/worktrunk
- Commit
a1de9c7
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.