Agent skill
agent-cli
Patterns for building CLIs that serve both humans and AI agents. Covers tri-modal output (JSON/JSONL/human), typed exit codes, structured error contracts, zero-dependency arg parsing, topic-based help, service discovery, field projection, and auto agent-mode detection. Reference implementation: @side-quest/observability CLI. Use when: building a CLI, adding a command, CLI output format, agent-friendly CLI, machine-readable output, JSON CLI contract, exit codes, --json flag, NDJSON streaming, how should my CLI work with agents, CLI design patterns.
Install this agent skill to your Project
npx add-skill https://github.com/nathanvale/side-quest-marketplace/tree/main/TO_AUDIT/skills/patterns
SKILL.md
Agent-Native CLI Patterns
Patterns for building CLIs that work for humans and AI agents, based on the @side-quest/observability reference implementation.
Reference Implementation
File: packages/server/src/cli/command.ts (1634 lines)
Tests: packages/server/src/cli/command.test.ts
Repo: ~/code/side-quest-observability
This is a production CLI that demonstrates every pattern documented here. When answering questions, read the relevant sections of command.ts to show real code -- not hypothetical examples.
Classification
Route the user's question to the appropriate reference file based on their intent.
| Intent | Trigger Signals | Reference File |
|---|---|---|
| Output format | JSON, JSONL, human output, --json, machine-readable, output contract | references/output-contract.md |
| Exit codes | exit code, return code, error code, process exit, status code | references/exit-codes.md |
| Error handling | error format, error contract, stderr, structured errors, error JSON | references/error-handling.md |
| Arg parsing | parse args, flags, commands, zero-dep, yargs alternative, commander | references/arg-parsing.md |
| Help system | --help, topic help, self-documenting, help text, usage | references/help-system.md |
| Service discovery | port file, pid file, find server, discovery, cache dir | references/service-discovery.md |
| Field projection | --fields, dot-path, minimal output, tokens, field selection | references/field-projection.md |
| Agent mode | non-TTY, headless, --non-interactive, pipe detection, automation | references/agent-mode.md |
| Community research | who's doing this, sources, references, prior art, standards | references/community-sources.md |
For questions that span multiple topics, read the primary reference first, then supplement from related references.
Response Structure
When answering a question routed through this skill:
- Direct answer - one line answering the specific question
- Pattern explanation - describe the pattern with code from the reference implementation (read the actual file, don't invent code)
- Implementation checklist - concrete steps to implement this pattern
- Community validation - cite 1-2 community sources that validate this approach (from
references/community-sources.md)
Examples
"How should I format my CLI output for agents?"
Route to: references/output-contract.md
Answer flow: Explain tri-modal output (human/JSON/JSONL) -> show writeSuccess from command.ts -> checklist for adding a new command -> cite joelclaw.com and Laminar.
"What exit codes should my CLI use?"
Route to: references/exit-codes.md
Answer flow: Show the typed exit code table -> explain why typed codes matter for agents -> show the TypeScript type -> checklist -> note that no community standard exists yet.
"Should I use commander or yargs?"
Route to: references/arg-parsing.md
Answer flow: Recommend zero-dep manual parsing -> show the discriminated union pattern -> explain agent compatibility -> cite @yacineMTB -> checklist.
"How do I make my CLI work in CI/CD pipelines?"
Route to: references/agent-mode.md
Answer flow: Explain auto non-TTY detection -> show shouldUseAutomaticMachineMode() -> explain --non-interactive -> cite Laminar and @Douglance -> checklist.
Core Principle
Every CLI command has three audiences: humans at a terminal, agents parsing output, and agents piping to other tools. Design for all three simultaneously.
This means:
- Human mode (default): Prose output with prefixed lines, readable formatting
- JSON mode (
--json): Structured envelope on stdout, parseable by agents - JSONL mode (
--jsonl): One JSON object per line, pipeable tojq, other CLIs, or agent chains - Auto mode: When stdout is not a TTY, automatically switch to machine-friendly output
What This Skill Does NOT Cover
- HTTP API design (that's a different pattern set)
- MCP server implementation (see MCP builder skill)
- General TypeScript patterns (future engineering skill)
- Testing patterns for CLIs (future engineering skill)
- Deployment or packaging (see bun-typescript-starter)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
nathanvale/side-quest-marketplace
cli-mcp-decision
Decide whether a workflow should use CLI skills, MCP, or a hybrid approach. Use when planning agentic tooling, writing ADRs, or evaluating migrations between CLI and MCP.
nathanvale/side-quest-marketplace
explain-codebase
Generate an engaging, deep-dive explanation document (FOR_[NAME].md) that explains a codebase or domain in plain language with analogies, lessons learned, and practical wisdom.
nathanvale/side-quest-marketplace
vscode-bookmarks
Create and manage VS Code Bookmarks extension labeled bookmarks in .vscode/bookmarks.json. Use when the user wants to add navigation bookmarks to a codebase, trace data flows through code, mark important code locations, or set up labeled waypoints for code walkthroughs. Also use when user says "bookmark", "label this code", "mark this flow", or "add waypoints".
nathanvale/side-quest-marketplace
manage-plugins
Add or remove inline plugins from the ccdev function in dotfiles .zshrc
nathanvale/side-quest-marketplace
observability
Start, stop, or check status of the Side Quest observability event server. Use when asked to start the server, stop the server, check server status, or manage the observability dashboard lifecycle.
nathanvale/side-quest-marketplace
node-cert
Fix Node.js certificate trust issues behind corporate SSL-inspecting proxies. Use when discussing: VPN, corporate VPN, corporate proxy, SSL inspection, MITM proxy, TLS interception, NODE_EXTRA_CA_CERTS, self-signed certificate error, UNABLE_TO_VERIFY_LEAF_SIGNATURE, certificate chain, proxy CA, corporate network, Claude Code on VPN, Gemini CLI on VPN, npm behind proxy, Node.js certificate error, CAFile.pem, proxy-on, proxy-off, HTTPS_PROXY, HTTP_PROXY, openssl s_client, certificate extraction, corporate root CA, forward trust CA, trust store gap.
Didn't find tool you were looking for?