agentleFS
Sign inStart free
saffron-healthsaffron-health/libretto/.agents/skills/cli-development/SKILL.md

cli-development

Skill883 starsChanged 3 months agoMITView on GitHub

Design and implement command-line interfaces with subcommand-scoped help, actionable success output, and debuggable failure output. Use when creating or modifying CLI commands, argument parsing, help and usage text, exit codes, or command UX for humans and agents.

We split this skill into the rules it gives an agent

18 rules. 0 are common, 16 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 16

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep output minimal and context-efficient.

    line 20
  2. Distinctive:

    Keep root help high-level.

    line 24
  3. Distinctive:

    Put detailed flags, examples, and edge cases in subcommand help.

    line 25
  4. Distinctive:

    Use stable wording and field names.

    line 30
  5. Distinctive:

    Avoid random ordering in lists.

    line 31
  6. Distinctive:

    Use conventional stream behavior.

    line 32
  7. Distinctive:

    Write primary result data to stdout.

    line 33
  8. Distinctive:

    Write diagnostics, warnings, and human-oriented guidance to stderr.

    line 34
  9. Distinctive:

    Document that automation should capture both stdout and stderr for full logs.

    line 36
  10. Very specific:

    Add machine-readable output mode such as --json.

    line 41
  11. Distinctive:

    Keep human-readable output as the default.

    line 42
  12. Very specific:

    Add --dry-run for mutating commands.

    line 44
  13. Distinctive:

    Use this pattern for each subcommand:

    line 49
  14. Distinctive:

    When returning an error, format output in this order:

    line 57
  15. Distinctive:

    Write subcommand help before command logic.

    line 94
  16. Distinctive:

    Verify stream contract: parseable payloads on stdout, diagnostics on stderr.

    line 97
  17. Distinctive:

    Add tests for success, parser errors, and runtime failures.

    line 98
  18. Distinctive:

    Verify each failure path includes state and next steps.

    line 99

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CLI Development

Build CLIs that stay actionable in both success and failure paths.

Core Principles

  1. Avoid dead ends.
    • Print next steps when a reasonable next action exists.
    • On terminal completion, state that no further action is required.
  2. Make failures diagnosable.
    • Print known state, failed operation, and likely cause.
    • Include recovery commands and focused help text.
    • Include usage text for argument or syntax errors.
  3. Keep output minimal and context-efficient.
    • Use short defaults.
    • Show detail only when requested by flags or when needed to recover from failure.
  4. Scope help to subcommands.
    • Keep root help high-level.
    • Put detailed flags, examples, and edge cases in subcommand help.

Command Contract

  1. Keep output deterministic.
    • Use stable wording and field names.
    • Avoid random ordering in lists.
  2. Use conventional stream behavior.
    • Write primary result data to stdout.
    • Write diagnostics, warnings, and human-oriented guidance to stderr.
    • In machine mode (--json), print a complete structured success or error object to stdout.
    • Document that automation should capture both stdout and stderr for full logs.
  3. Return meaningful exit codes.
    • 0 for success.
    • Non-zero codes map to clear failure classes.
  4. Support automation.
    • Add machine-readable output mode such as --json.
    • Keep human-readable output as the default.
  5. Support safe execution.
    • Add --dry-run for mutating commands.
    • Make retry behavior explicit.

Help and Error Pattern

Use this pattern for each subcommand:

  1. One-line purpose.
  2. Usage line.
  3. Required arguments.
  4. Optional flags.
  5. Examples, including one failure-recovery example.

When returning an error, format output in this order:

  1. Error summary.
  2. Known state.
  3. Recovery options.
  4. Exact next command.
  5. Relevant subcommand help hint.

Output Templates

Success with next step:

Created release r123.
Next: mycli release publish r123

Success without next step:

Published release r123.
No further action required.

Failure with recovery:

Error: failed to publish release r123 (artifact missing).
Known state: release exists, build step did not produce dist/app.tar.gz.
Try: mycli release build r123
Then: mycli release publish r123
Help: mycli help release publish

Implementation Checklist

  • Define root command and subcommand boundaries.
  • Write subcommand help before command logic.
  • Implement parser and validate required arguments.
  • Implement success and failure output contracts.
  • Verify stream contract: parseable payloads on stdout, diagnostics on stderr.
  • Add tests for success, parser errors, and runtime failures.
  • Verify each failure path includes state and next steps.

Download now (ZIP)

  • Other versions7 projects use a version of this.

    Word for word · 1

    1. cashew-labs/libretto★ 898100% same

    Edited · 0

    None found.

    Wrote their own version · 6

    1. irahardianto/awesome-agv★ 157same name
    2. nimadorostkar/Claude-Skills-collection★ 33same name
    3. fmind/dot★ 12same name
    4. fmind/dotfiles★ 11same name
    5. DebugSwift/XcodeBazelMCP★ 9same name
    6. KMaruthi2002/universal-llm-skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use documentation-site, agent-protocols and 4 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • fmindSkill

      documentation-site

      Build Zensical docs sites: navigation, API docs, Pages, MkDocs/Hugo migration.

      Also in 3 projects that use this

    • insodimensionSkill

      agent-protocols

      Guide agent harness engineering toward the right AI agent protocol standards (MCP, A2A, ACP, AG-UI, AP2, x402, etc.) instead of reinventing. Analyzes what you're building, recommends protocols, pulls spec details and wire-message examples, checks compliance, and surfaces contribution opportunities. Triggers: '/agent-protocols', 'which protocol', 'should I use MCP or', 'what protocol for', 'agent protocol', 'protocol selection', 'MCP vs A2A', 'wire protocol for agents', 'agent interop', 'agent standard', 'extend MCP', 'contribute to A2A', 'protocol compliance', 'agent transport', 'agent discovery'. Self-improving: every run ends with a gotcha review.

      Also in 3 projects that use this

    • third-order-labsSkill

      project-scaffolding

      Templates, directory conventions, and document structure for long-form fiction projects. Contains the full template library — documents are created as the project needs them, not all at once.

      Also in 3 projects that use this

    • mjunaidcaSkill

      kubernetes

      Production-grade Kubernetes manifests and debugging for containerized applications. This skill should be used when users ask to deploy to Kubernetes, create K8s manifests, containerize for K8s, set up Deployments/Services/Jobs/StatefulSets/CronJobs, create namespaces with resource quotas, set up multi-team isolation, configure ResourceQuota/ LimitRange, secure with RBAC (ServiceAccount, Role, RoleBinding), configure init containers (model download, db wait, migrations), set up sidecars (logging, metrics), or debug pods (CrashLoopBackOff, logs, exec, describe, events). Auto-detects from Dockerfile/code, generates hardened manifests with educational comments. CKAD-aligned.

      Also in 4 projects that use this

    • AnthropicSkill

      incident-response

      Run an incident response workflow — triage, communicate, and write postmortem. Trigger with "we have an incident", "production is down", an alert that needs severity assessment, a status update mid-incident, or when writing a blameless postmortem after resolution.

      Also in 5 projects that use this

    • OpenAISkill

      observability

      Vercel Observability expert guidance — Drains (logs, traces, speed insights, web analytics), Web Analytics, Speed Insights, runtime logs, custom events, OpenTelemetry integration, and monitoring dashboards. Use when instrumenting, debugging, or optimizing application performance and user experience on Vercel.

      Also in 4 projects that use this

  • In this repository30 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free