$ loading_
Design and evaluate CLI tools and developer SDK architecture and usability.
Copy the install command and let the AI configure it · recommended for beginners
Please install the "system-type-cli-tool" skill from askskill: 1. Download https://raw.githubusercontent.com/microsoft/amplifier-bundle-systems-design/main/skills/system-type-cli-tool/SKILL.md 2. Save it as ~/.claude/skills/system-type-cli-tool/SKILL.md 3. Reload skills and tell me it's ready
Design a command structure for a cloud deployment CLI, including subcommand hierarchy, global flags, configuration precedence, error code conventions, and sample commands.
A clear CLI information architecture with command tree, flag conventions, config loading order, and usage examples.
Evaluate this developer SDK versioning plan, focusing on API compatibility, deprecation strategy, plugin extension points, and migration cost, then suggest improvements.
A compatibility assessment highlighting risks, breaking changes, and safer evolution recommendations.
Define shell completion, environment variable support, output formatting rules, and handling strategies for common failure scenarios in a local development CLI.
An actionable integration and robustness plan that improves CLI experience, observability, and fault tolerance.
Patterns, failure modes, and anti-patterns for command-line tools and developer-facing libraries.
What it is. Top-level command dispatches to subcommands, each with its own flags and arguments. tool <subcommand> [flags] [args]. The dominant pattern for non-trivial CLIs.
When to use. Tools with more than ~5 distinct operations. When operations have different flag sets. When you want discoverability — tool help lists all subcommands.
When to avoid. Single-purpose tools that do one thing (e.g., curl, jq). Adding subcommands to a tool that does one thing well makes it do many things poorly.
Nesting depth. Two levels (tool resource action) is the practical limit. Three levels (tool group resource action) works if the grouping is obvious (e.g., kubectl get pods). Four levels means your CLI needs a redesign.
POSIX short flags. Single dash, single letter: -v, -f. Combinable: -vvv for verbosity levels, -rf for multiple flags. Every short flag should have a long equivalent.
GNU long flags. Double dash, full words: --verbose, --output-format. Self-documenting. Use hyphens, not underscores.
Boolean flags. --color enables, --no-color disables. Pick a sensible default and provide the negation. Don't require --color=true.
Value flags. --output json or --output=json. Support both forms. Be consistent across all flags.
The -- separator. Everything after -- is a positional argument, not a flag. Mandatory for tools that accept arbitrary user input — without it, tool delete --force is ambiguous (is --force a flag or an argument?).
Positional args are for the primary noun — the thing being operated on. tool build ./src, tool deploy production. One or two positional args maximum. After that, you need flags.
Flags are for everything that modifies behavior. If the user could reasonably forget to provide it and get a useful default, it's a flag, not a positional arg.
Rule of thumb. If you're reading the help text to remember which positional arg is which, they should be flags.
Global flags apply to every subcommand: --verbose, --config, --output-format, --no-color. Define them once at the root. They should be few and genuinely universal.
Local flags belong to a specific subcommand. Don't pollute the global namespace with flags only one subcommand uses.
Interactive prompts are for first-run setup, destructive confirmations, and guided workflows (tool init). Always provide a flag equivalent (--yes, --name=foo) so scripts can bypass prompts.
TTY detection. If stdin is not a TTY, never prompt. Fail with an actionable error telling the user which flag to pass. A CI pipeline hanging on a prompt is a production incident.
stdout is for program output — the data the user asked for. It must be parseable. If someone pipes your output, only the data should flow through.
stderr is for human messages — progress indicators, warnings, debug info, error messages. Everything that isn't the requested data.
stdin is for data input. Accept - as a filename to mean stdin. Support piping: cat file | tool process and tool process < file.
The test. tool list | wc -l should return a correct count. If your progress spinner or status message contaminates stdout, you've broken the Unix contract.
Highest precedence wins. The standard order:
TOOLNAME_FLAGNAME (e.g., GIT_AUTHOR_NAME).…
Design and assess enterprise integration patterns, legacy modernization, and orchestration strategies.
Review system designs with a seven-step method to surface risks and improvements.
Evaluate system designs through Unix/Linux principles for simplicity and composability.
Design or assess Azure system architectures, operations, and cloud service choices.
Design and evaluate data pipelines, streaming systems, and ETL architecture patterns.
Design offline-first edge systems with sync, conflict handling, and weak-network resilience.
Design or evaluate web services, APIs, scalability, and reliability tradeoffs.
Design or assess SPA architecture across routing, state, performance, and offline support.
Design CLI tools with simple installs, command routing, and layered config.
Design and evaluate event-driven, message-based, and asynchronous system architectures.
Design and assess ML training, serving, and experimentation system architectures.
Design and evaluate real-time collaborative systems, sync flows, and failure handling.