cli-design-expert

Files (1)

• SKILL.md

SKILL.md (first lines)

---

name: cli-design-expert
version: "2.0.0"
compatibility: CLAUDE.md v2.3.0+

---

## Protocol Integration

### DECISION LOOP Position

This skill applies at **step 5** of the DECISION LOOP:

```
1. CLASSIFY  -> complexity? backup needed? tools?
2. PROTECT   -> cp file file.bak (for configs, DBs)
3. MEMORY    -> query relevant context + past failures
4. AGENTS    -> check overlaps (if multi-agent)
5. SKILLS    -> @Skill:cli-design-expert.md for domain-specific guidance
6. WORK      -> implement (ALWAYS use worktree for ANY file changes)
7. REVIEW    -> self-review diff before testing
8. TEST      -> completion gates pass
9. LEARN     -> store outcome in memory
```

# CLI Design Expert

## Overview

This skill provides expert guidance for designing and implementing professional CLI tools with:

- **Intuitive UX**: Commands that work as users expect
- **Progressive Disclosure**: Simple by default, powerful when needed
- **Excellent Help**: Self-documenting commands with rich examples
- **Error Recovery**: Helpful errors that guide users to success
- **Professional Polish**: Consistent styling, colors, and output formatting

## PROACTIVE USAGE

**Invoke this skill before:**

- Creating new CLI commands
- Designing command structures
- Writing help text and documentation
- Implementing error messages
- Adding interactive prompts

---

## Critical Design Principles

### 1. Command Structure - Follow Git's Model

```bash
# Noun-verb pattern (preferred)
uap memory query          # <tool> <resource> <action>
uap worktree create       # <tool> <resource> <action>

# Common structure
<tool> <command> [subcommand] [arguments] [--options]

# Examples
uap init                              # Simple command
uap init --interactive               # With flag
uap generate --output ./out          # With option value
uap memory query "search term"       # With argument
uap worktree create fix-bug --base develop  # Full example
```

### 2. Option Naming Conventions

```bash
# Short + Long options (always provide both for common options)
-v, --version           # Version
-h, --help              # Help
-o, --output <path>     # Output path
-f, --force             # Force/overwrite
-q, --quiet             # Suppress output
-d, --debug             # Debug mode
-n, --dry-run           # Preview without changes

# Flags (boolean) vs Options (values)
--verbose               # Flag (boolean)
--format json           # Option with value
--count 10              # Option with number

# Negatable flags
--color / --no-color    # Allow disabling defaults
--cache / --no-cache
```

### 3. Exit Codes

```typescript
// Standard exit codes
const EXIT_SUCCESS = 0; // Success
const EXIT_ERROR = 1; // General error
const EXIT_USAGE = 2; // Invalid usage/arguments
const EXIT_CONFIG = 78; // Configuration error
const EXIT_NOINPUT = 66; // Input file not found
const EXIT_CANTCREAT = 73; // Can't create output

// Usage
process.exit(EXIT_SUCCESS);
process.exit(EXIT_ERROR);
```

---

## Help System Design

### 1. Three Levels of Help

```bash
# Level 1: Command overview (--help on root)
$ uap --help
Universal Agent Memory - AI agent memory and workflow system

From DammianMiller/universal-agent-protocol, MIT.

More from DammianMiller/universal-agent-protocol