Clack CLI Patterns
Defines consistent interactive prompt, --quiet, and -- output contracts for OpenChamber terminal commands, so policy validation always precedes presentation in every run mode.
This is a pure documentation-style coding convention with no executable scripts, no network/filesystem side effects, and no data collection; no red-line risk exists. The mode contract explicitly requires validation before presentation, no hanging in non-TTY, and strict JSON output—good safety orientation. Deducted for: no rollback mechanisms, source attribution limited to vague repo paths, and unverified publisher.
Instructions are internally self-consistent: the mode table, completion criteria, and snippets align; snippets.md matches the main doc; failure feedback (non-zero exits, JSON error payloads) is well specified. Deducted for: static review cannot verify that @clack/prompts usage matches the actual implementations in precedent files like packages/web/bin/cli.js, and there is no test evidence covering the skill's key paths, so staying conservative within the static cap.
Trigger conditions are clear (creating/modifying OpenChamber CLI commands, prompts, --quiet/-- behavior), with explicit exclusions for web UI and VS Code styling—good boundary declarations. Deducted for: applicability limited to this single repository's CLI, no Chinese-language support notes, and reliance on the GitHub ecosystem.
Well-layered structure (overview → mode contract → primitive standard → output contracts → completion criteria → snippet references), MIT license, explicit scope exclusions, and known-limitation disclosure in the checklist. Deducted for: no version number or changelog for the skill itself, no FAQ/troubleshooting section, and maintenance responsibility not stated in the skill files.
As an internal coding convention it provides reusable patterns, snippets, and a completion checklist with real marginal value for keeping the CLI consistent across five modes—beyond a verbal convention. Deducted for: output is a specification rather than a directly usable artifact; value depends on correct adherence; static review cannot verify real outcomes and no alternatives comparison is given.
The main doc and snippets.md corroborate each other, and it cites concrete precedent files (cli.js, cli-output.js) for audit. Deducted for: those precedent files are absent from the provided material; the 'must have tests for five modes' requirement is only a claim, with no reproducible tests or third-party execution evidence for this skill—conservative within the static cap of 5.
- The skill applies only to terminal CLI development within the OpenChamber repository; it does not fit other projects, so verify the target repository before semantic invocation.
- Precedent files referenced by the skill (cli.js, cli-output.js) were not provided in this review; static review cannot confirm consistency—manually verify before use.
- The skill itself has no version number or changelog; content may change silently on update—consider pinning revisions.
- It demands test coverage across five modes but ships no runnable tests; adoption cost falls on the implementer.
What does this skill do, and when should you use it?
This skill lives at .agents/skills/clack-cli-patterns/SKILL.md inside the openchamber/openchamber repository — a desktop and web interface for the OpenCode AI agent — and is MIT licensed. It establishes how the @clack/prompts-based terminal CLI should behave: policy-first, UX-second, with interactive prompts as presentation only, never enforcement. It specifies a mode contract covering interactive TTY, fully specified flags, non-TTY, --quiet, and -- modes, each with prompt, output, and failure semantics. It also standardizes Clack primitives and a centralized thin output-adapter pattern. Scope is terminal CLI work only (e.g. packages/web/bin/*); web UI and VS Code webview styling are explicitly out of scope.
This is an instruction document, not executable code. It guides developers or agents writing or modifying OpenChamber CLI commands to: run safety and correctness validation before presentation in every mode; allow prompts only when input is missing in interactive TTY (never in non-TTY, --quiet, or --); handle cancellation via isCancel + cancel(...) and consistent SIGINT exit semantics; use Clack primitives per standard (intro/outro, log.*, note vs box, spinner/progress/tasks); centralize imports and helpers in one adapter module (isJsonMode, isQuietMode, shouldRenderHumanOutput, canPrompt, createSpinner, createProgress, printJson); emit concise machine-friendly lines under --quiet; and emit strict JSON-only output with non-zero exit codes under --. A references/snippets.md file provides reusable snippets for prompt guards, non-interactive fallback, spinner lifecycle, and output branching.
- An OpenChamber contributor adding a new CLI subcommand that must satisfy interactive, --quiet, --, and non-TTY output with consistent exit codes
- A developer adding spinner feedback for long-running operations (e.g. tunnel start/stop) that must stay non-animated in quiet/ modes
- An agent generating deterministic, script-safe output for piped pipelines without interactive prompts hanging
- A team unifying error guidance with short stable codes like [PORT_MISMATCH] for quick scanning
- A reviewer checking that an existing command meets the skill's five completion criteria (default TTY, quiet, , non-TTY, error paths)
What are this skill's strengths and limitations?
- A concrete mode-contract table removes ambiguity about prompts, output, and failure semantics per run mode
- Provides a copyable list of thin adapter helpers (isJsonMode, createSpinner, printJson, etc.) plus reference file paths in the codebase
- Covers detailed UX rules: intro/outro pairing, spinner.clear(), dependency-ordered prompt flows, initialValue prefills, narrow-terminal readability
- Includes a loadable references/snippets.md with snippets for prompt guards, non-interactive fallback, and spinner lifecycle
- Tightly coupled to the OpenChamber codebase (packages/web/bin/*, @clack/prompts); adapting to other projects requires edits
- No evidence of an automated test suite enforcing the completion criteria — they are stated as a checklist only
- No guidance on substituting Clack primitives in projects that don't use @clack/prompts
- The repo README describes the whole OpenChamber application; there is no standalone data on this skill's maturity, usage, or community feedback
How do you install this skill?
The skill ships with the openchamber/openchamber repository at .agents/skills/clack-cli-patterns/. To get it: git clone https://github.com/openchamber/openchamber, then copy the .agents/skills/clack-cli-patterns folder into your Agent Skills-compatible client's skills directory (e.g. .agents/skills/ for Claude Code). The repository README does not document skill-specific installation steps; reusable snippets are at references/snippets.md within the skill folder.
How do you use this skill?
The agent loads the skill when creating or modifying OpenChamber CLI commands, prompts, terminal output, non-TTY behavior, or --quiet/-- behavior, per its description. You can also trigger it explicitly: "Implement the five-mode output contract for this new CLI command following the clack-cli-patterns skill." During implementation, load references/snippets.md as instructed and place validators before every mode branch. Implementation is complete when all five cases — default TTY, --quiet, --, non-TTY, and error paths in human and modes — produce deterministic output and exit behavior.
How does this skill compare with similar options?
No direct alternative is named in the source; the skill positions itself as the canonical CLI parity and safety policy for OpenChamber.