# Client Interface Guidelines

> Design or review machine-primary command-line client interfaces for agent execution. Use when creating or improving CLI/client tools that require stable JSON contracts, deterministic outputs, structured errors, non-interactive operation, robust exit codes, secure secret handling, and operator inspection paths without turning the CLI into a human-first UI.

- Skill: `wisdom-in-a-nutshell/client-interface-guidelines` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add wisdom-in-a-nutshell/client-interface-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wisdom-in-a-nutshell/client-interface-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wisdom-in-a-nutshell (https://skillmd.com/u/wisdom-in-a-nutshell)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wisdom-in-a-nutshell/client-interface-guidelines

---


# Client Interface Guidelines

## Overview

Apply this skill as the default gate for agent-native CLI/client tools.

Optimize for machine reliability first.
Treat operator inspection as a secondary debugging and status layer, not as a co-equal interface mode.

## Workflow

1. Read `references/00-how-to-use-this-skill.md`.
2. Start with `references/09-agent-first-contract.md`.
3. Apply `references/10-agent-must-should-checklist.md`.
4. Validate using `references/11-agent-test-matrix-template.md`.
5. Use `references/12-delivery-route-selection.md` when a CLI chooses between local device, remote beta, cloud build, or other delivery routes.
6. Use `references/02` to `07` for detailed guidance.
7. Optionally run `references/08-quick-review-checklist.md` for full coverage.

## Reference Files

- `references/00-how-to-use-this-skill.md`
- `references/01-philosophy.md`
- `references/02-basics-help-docs.md`
- `references/03-output-errors.md`
- `references/04-arguments-interactivity-subcommands.md`
- `references/05-robustness-future-signals.md`
- `references/06-configuration-environment.md`
- `references/07-naming-distribution-analytics.md`
- `references/08-quick-review-checklist.md`
- `references/09-agent-first-contract.md`
- `references/10-agent-must-should-checklist.md`
- `references/11-agent-test-matrix-template.md`
- `references/12-delivery-route-selection.md`

## Non-Negotiables

- Stable machine-readable contract and schema versioning.
- Non-interactive operation with `--no-input` support.
- Structured errors with stable codes and mapped exit codes.
- Strict stdout/stderr separation.
- Secure secret handling with no flag/env secret input.
- Additive interface evolution with explicit deprecation path.
- JSON is the default behavioral contract unless there is a strong reason otherwise.