Skip to main content
affpapa.org
RU EN
skill CX Codex

unix-cli — Claude Code skill: POSIX rules for CLI tools

A rule set that steers your AI agent when it writes or reviews command-line tools: flags, exit codes, output streams.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill unix-cli -a claude-code
Open on GitHub

What unix-cli does

The skill packs 44 rules into 8 categories, ordered by impact. Argument parsing, exit codes and output streams sit at the top; configuration and environment variables at the bottom. Every rule lives in its own file under references/ with an explanation and code samples, so the agent pulls in only what the task needs — flags, stdout/stderr, signals, shell scripts.

The rules follow POSIX conventions. Data goes to stdout, diagnostics to stderr, zero means success, and a process killed by a signal returns 128+N. Separate entries cover --help and --version, -- as an option terminator, NO_COLOR, and the XDG Base Directory spec. On secrets the guidance is blunt: don't read them from command-line flags and don't keep them in config files.

Reach for this when your tool has to survive a pipeline next to grep and xargs. Without it an agent will happily print a progress bar to stdout and break the pipe. Install runs through npx skills add; GitHub Copilot uses gh skill install instead.

What it helps with

  • parse flags and positional arguments the standard way
  • pick an exit code for partial success
  • keep data and diagnostics on separate streams
  • handle SIGINT and SIGPIPE without junk in the output
  • audit an existing tool for pipeline compatibility

Example prompts for the agent

  • write a Python CLI that reads a file list from stdin and prints results to stdout
  • review my script for POSIX compliance: exit codes, stderr, SIGINT handling
  • add --help, --version and support for -- as an option terminator

How to install unix-cli

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill unix-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/unix-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/unix-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about unix-cli

How do I install unix-cli in Claude?

Run npx skills add pproenca/dot-skills --skill unix-cli -a claude-code. The skill lands at ~/.claude/skills/unix-cli/SKILL.md.

What does unix-cli do?

It hands the agent a rule set for writing and reviewing command-line tools: arguments, exit codes, output streams, signals, configuration. Rules are grouped by priority, critical first.

Which platforms does the skill support?

Besides Claude there are install paths for Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. GitHub Copilot uses a different command: gh skill install pproenca/dot-skills unix-cli.

Source text

SKILL.md · MIT 
---
name: unix-cli
description: UNIX command-line interface guidelines for building tools that follow POSIX conventions, proper exit codes, stream handling, and the UNIX philosophy. This skill should be used when writing, reviewing, or designing CLI tools to ensure they integrate properly with the UNIX tool chain. Triggers on tasks involving CLI tools, command-line arguments, exit codes, stdout/stderr, signals, or shell scripts.
---

# UNIX/POSIX Standards CLI Best Practices

Comprehensive guidelines for building command-line tools that follow UNIX conventions, designed for AI agents and LLMs. Contains 44 rules across 8 categories, prioritized by impact from critical (argument handling, exit codes, output streams) to incremental (configuration and environment).

## When to Apply

Reference these guidelines when:
- Writing new CLI tools in any language
- Parsing command-line arguments and flags
- Deciding what goes to stdout vs stderr
- Choosing appropriate exit codes
- Handling signals like SIGINT and SIGTERM

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Argument & Flag Design | CRITICAL | `args-` |
| 2 | Exit Codes | CRITICAL | `exit-` |
| 3 | Output Streams | CRITICAL | `output-` |
| 4 | Error Handling | HIGH | `error-` |
| 5 | I/O & Composition | HIGH | `io-` |
| 6 | Help & Documentation | MEDIUM-HIGH | `help-` |
| 7 | Signals & Robustness | MEDIUM | `signal-` |
| 8 | Configuration & Environment | MEDIUM | `config-` |

## Quick Reference

### 1. Argument & Flag Design (CRITICAL)

- [`args-use-getopt`](references/args-use-getopt.md) - Use standard argument parsing libraries
- [`args-provide-long-options`](references/args-provide-long-options.md) - Provide long options for all short options
- [`args-support-double-dash`](references/args-support-double-dash.md) - Support double-dash to terminate options
- [`args-require-help-version`](references/args-require-help-version.md) - Implement --help and --version options
- [`args-prefer-flags-over-positional`](references/args-prefer-flags-over-positional.md) - Prefer flags over positional arguments
- [`args-use-standard-flag-names`](references/args-use-standard-flag-names.md) - Use standard flag names
- [`args-never-read-secrets-from-flags`](references/args-never-read-secrets-from-flags.md) - Never read secrets from command-line flags
- [`args-support-option-bundling`](references/args-support-option-bundling.md) - Support option bundling

### 2. Exit Codes (CRITICAL)

- [`exit-zero-for-success`](references/exit-zero-for-success.md) - Return zero for success only
- [`exit-use-standard-codes`](references/exit-use-standard-codes.md) - Use standard exit codes
- [`exit-signal-codes`](references/exit-signal-codes.md) - Use 128+N for signal termination
- [`exit-partial-success`](references/exit-partial-success.md) - Handle partial success consistently
- [`exit-distinguish-error-types`](references/exit-distinguish-error-types.md) - Distinguish error types with different exit codes

### 3. Output Streams (CRITICAL)

- [`output-stdout-for-data`](references/output-stdout-for-data.md) - Write data to stdout only
- [`output-stderr-for-errors`](references/output-stderr-for-errors.md) - Write errors and diagnostics to stderr
- [`output-detect-tty`](references/output-detect-tty.md) - Detect TTY for human-oriented output
- [`output-provide-machine-format`](references/output-provide-machine-format.md) - Provide machine-readable output format
- [`output-line-based-text`](references/output-line-based-text.md) - Use line-based output for text streams
- [`output-respect-no-color`](references/output-respect-no-color.md) - Respect NO_COLOR environment variable

### 4. Error Handling (HIGH)

- [`error-include-program-name`](references/error-include-program-name.md) - Include program name in error messages
- [`error-actionable-messages`](references/error-actionable-messages.md) - Make error messages actionable
- [`error-use-strerror`](references/error-use-strerror.md) - Use strerror for system errors
- [`error-avoid-stack-traces`](references/error-avoid-stack-traces.md) - Avoid stack traces in user-facing errors
- [`error-validate-early`](references/error-validate-early.md) - Validate input early and fail fast

### 5. I/O & Composition (HIGH)

- [`io-support-stdin`](references/io-support-stdin.md) - Support reading from stdin
- [`io-write-to-stdout`](references/io-write-to-stdout.md) - Write output to stdout by default
- [`io-be-stateless`](references/io-be-stateless.md) - Design stateless operations
- [`io-handle-binary-safely`](references/io-handle-binary-safely.md) - Handle binary data safely
- [`io-atomic-writes`](references/io-atomic-writes.md) - Use atomic file writes
- [`io-handle-multiple-files`](references/io-handle-multiple-files.md) - Handle multiple input files consistently

### 6. Help & Documentation (MEDIUM-HIGH)

- [`help-show-usage-on-error`](references/help-show-usage-on-error.md) - Show brief usage on argument errors
- [`help-structure-help-output`](references/help-structure-help-output.md) - Structure help output consistently
- [`help-show-defaults`](references/help-show-defaults.md) - Show default values in help
- [`help-include-examples`](references/help-include-examples.md) - Include practical examples in help
- [`help-version-format`](references/help-version-format.md) - Format version output correctly

### 7. Signals & Robustness (MEDIUM)

- [`signal-handle-sigint`](references/signal-handle-sigint.md) - Handle SIGINT gracefully
- [`signal-handle-sigterm`](references/signal-handle-sigterm.md) - Handle SIGTERM for clean shutdown
- [`signal-handle-sigpipe`](references/signal-handle-sigpipe.md) - Handle SIGPIPE for broken pipes
- [`signal-cleanup-on-second-interrupt`](references/signal-cleanup-on-second-interrupt.md) - Skip cleanup on second interrupt

### 8. Configuration & Environment (MEDIUM)

- [`config-follow-xdg`](references/config-follow-xdg.md) - Follow XDG Base Directory Specification
- [`config-precedence-order`](references/config-precedence-order.md) - Apply configuration in correct precedence order
- [`config-env-naming`](references/config-env-naming.md) - Use consistent environment variable naming
- [`config-never-store-secrets`](references/config-never-store-secrets.md) - Never store secrets in config files or environment
- [`config-respect-standard-vars`](references/config-respect-standard-vars.md) - Respect standard environment variables

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →
unix-goto-development manutej Walks an agent through adding features to the unix-goto navigation tool: a 9-step workflow, 100% test coverage, and sub-100ms cached navigation. CX Codex +1 427installs hyva-exec-shell-cmd hyva-themes Identifies the Magento dev setup and selects the right command wrapper for containers or local execution. CX Codex +1 1,300installs bash-script-generator akin-ozer A skill that turns a task into a working bash script: captures requirements, writes the code, then validates it. CX Codex +1 670installs mcp-cli official github A skill that teaches the agent to reach MCP servers from the shell: list servers, read tool schemas, run calls with JSON arguments. 9,650installs debug-window davila7 Opens a live-tailing debug log window when Claude starts with --debug or -d, then closes it when the session ends. 189installs c-pro Seth Hobson A subagent for C code with memory ownership, system calls, and POSIX. Use it for systems, embedded, and performance-critical work. CX Codex 650installs

From the same set45

ast-grep A skill with community best practices for writing, reviewing and debugging ast-grep rules for code search, linting and rewriting. CX Codex +1 332installs 37signals-rails A rule set for Ruby on Rails the 37signals way: vanilla Rails, CRUD controllers, rich domain models, Hotwire. Useful when you write or refactor code and want to stay in that school. CX Codex +1 329installs mui-base A skill with 48 rules for building headless React component libraries the MUI Base UI way. Useful when logic and styling stay apart. CX Codex +1 328installs vhs A skill with 47 rules for VHS .tape files, so your agent writes and reviews terminal recordings that turn into GIFs and videos. CX Codex +1 323installs python A skill with 42 Python 3.11+ optimization rules: it steers the agent on async code, data structures and memory use. CX Codex +1 315installs rust-refactor A skill that walks an agent through Rust refactoring: dropping forwarded parameters, splitting large files, migrating types in steps. CX Codex +1 314installs 12-factor-app A skill with 51 rules from the Twelve-Factor App methodology. Useful when you design backend services, APIs or microservices and want a checklist to lean on. CX Codex +1 311installs js-google A skill that feeds your AI agent 47 JavaScript rules from Google's official style guide. Useful when writing, reviewing or refactoring JS. CX Codex +1 310installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor