# CLI Logging UX

Use this skill when editing or creating CLI output, logging, warnings, error messages...

- Repository: https://github.com/microsoft/apm (4171 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/apm --skill cli-logging-ux -g -a claude-code -y`
Codex: `npx skills add microsoft/apm --skill cli-logging-ux -g -a codex -y`
Cursor: `npx skills add microsoft/apm --skill cli-logging-ux -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/apm --skill cli-logging-ux -g -a gemini-cli -y`

## Description

Use this skill when editing or creating CLI output, logging, warnings, error messages, progress indicators, or diagnostic summaries in the APM codebase. Activate whenever code touches console helpers (_rich_success, _rich_warning, _rich_error, _rich_info, _rich_echo), DiagnosticCollector, STATUS_SYMBOLS, CommandLogger, or any user-facing terminal output, even if the user doesn't mention "logging" or "UX" explicitly.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

[CLI Logging UX expert persona](../../../.apm/agents/cli-logging-expert.agent.md)

# CLI Logging & Developer Experience

## Decision framework

Apply these three tests to every piece of user-facing output. If a message fails any test, redesign it.

### 1. The "So What?" Test

Every warning must answer: *what should the user do about this?*

```
# Fails, not actionable, user can't do anything
Sub-skill 'my-skill' from 'my-package' overwrites existing skill

# Passes, tells the user exactly what to do
Skipping my-skill, local file exists (not managed by APM). Use 'apm install --force' to overwrite.
```

If the user can't act on it, it's not a warning, it's noise. Demote to `--verbose` or remove.

### 2. The Traffic Light Rule

Use color semantics consistently. Never use a warning color for an informational state.

| Color | Helper | Meaning | When to use |
|-------|--------|---------|-------------|
| Green | `_rich_success()` | Success / completed | Operation finished as expected |
| Yellow | `_rich_warning()` | User action needed | Something requires user decision |
| Red | `_rich_error()` | Error / failure | Operation failed, cannot continue |
| Blue | `_rich_info()` | Informational | Status updates, progress, summaries |
| Dim | `_rich_echo(color="dim")` | Secondary detail | Verbose-mode details, grouping headers |

### 3. The Newspaper Test

Can the user scan output like headlines? Top-level = what happened. Details = drill down.

```
# Bad, warnings break the visual flow between status and summary
[checkmark] package-name
[warning] something happened
[warning] something else happened
  [tree] 3 skill(s) integrated

# Good, clean tree, diagnostics at the end
[checkmark] package-name
  [tree] 3 skill(s) integrated

── Diagnostics ──
  [warning] 2 skills replaced by a different package (last installed wins)
    Run with --verbose to see details
```

## Inline output vs deferred diagnostics

The rest: https://github.com/microsoft/apm/blob/HEAD/.agents/skills/cli-logging-ux/SKILL.md