Guides

Design guidance for CLI authors. Unlike failure modes (what goes wrong) and requirements (what to enforce), guides capture what to do — positive design principles that cannot be mechanically verified but materially improve agent compatibility.

---

Guide	Topic	Summary
Unix Naming Conventions	Naming, vocabulary, corpus alignment	How to exploit LLM Unix training as a design asset
Streaming vs Envelope Output	Output mode selection	When to stream by default vs return a buffered envelope
Designing AI-Native CLI Commands That Read from stdin	stdin handling, pipe safety	Three failure modes that silently break stdin-reading commands — and the patterns to fix them
The No-Args Entry Point	First-contact discoverability, argparse anti-pattern	Why bare invocation must exit 0 and how the argparse required=True default silently breaks agent discovery
Designing CLIs for Skill Optimization	Skill transferability, optimization prerequisites	How to make CLI behavior learnable and portable across agent runtimes — and which failure modes abort skill training entirely