skills.rest
nseng-ai
nseng-aiOFFICIAL
Explore all skills by this author →
GitHub

ns-cli-design

Enforces authoring discipline for Clinkr-based ns CLI commands serving human and agent audiences.

2|Updated Apr 2, 2026
Search Tags:#cli design#exit codes#command authoring#clinkr#machine envelope#danger tiers#agent-facing cli
One-click install
npx skills add https://github.com/nseng-ai/ns --skill ns-cli-design-nseng-ai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ns-cli-design
Source: https://github.com/nseng-ai/ns/tree/main/skills/internal/agent-engineering/ns-cli-design
Command: npx skills add https://github.com/nseng-ai/ns --skill ns-cli-design-nseng-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Designing CLI commands that serve both humans and AI agents is error-prone: machine output contracts drift, exit codes become inconsistent, prompts hang non-interactive callers, and destructive operations lack clear authorization gates. This Skill provides the canonical authoring rules, hard gates, and a pre-ship checklist so every ns CLI command ships with a stable, bounded, recoverable contract for both audiences. ## Core Features & Use Cases - Hard design gates: Enforces framework parser usage, stdout/stderr separation, coarse stable exit codes (ok=0, negative=1, failure/usageError=2), and a camelCase discriminated machine envelope published via --json-schema. - Danger tier discipline: Classifies commands into four tiers (read-only through high blast radius) with distinct --yes/-y confirmation versus --force/-f precondition-override semantics, plus TTY-gated prompting rules. - Reference library: Ships detailed references for the Clinkr API map with ADR rationale, human-tier UX rules, agent/exec-tier machine contract rules, danger tiers, and a pre-ship checklist. - Use Case: When adding a new ns CLI command or reviewing an existing one, load this Skill to verify the result envelope, exec subgroup placement, output bounding, and confirmation flow before shipping. ## Quick Start Ask the agent to review the design of a new ns CLI command against the ns-cli-design checklist before shipping it.

Frequently Asked Questions about ns-cli-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a CLI command that works for both humans and AI agents?▼

Build the command with the Clinkr framework parser, return a typed result envelope via ok/negative/failure/usageError constructors, and publish the machine schema with --json-schema. Human rendering may evolve freely, but the machine envelope must stay stable and change only additively.

What exit codes should a Clinkr CLI command use?▼

Use coarse stable exit codes: 0 for ok, 1 for negative (semantic non-success), and 2 for failure or usageError. Detailed failure semantics belong in the machine envelope via errorType and structured data, not in numeric exit codes.

When should CLI operations live under a hidden exec subgroup?▼

Skill-only or agent-only operations belong under an exec ClinkrGroup constructed with isHidden: true. Hiding suppresses the subgroup from parent help while keeping it invocable, keeping top-level help focused on commands a human would type.

What is the difference between --yes and --force flags in CLI design?▼

--yes confirms a Tier 2 destructive or external write that would otherwise prompt, while --force overrides a failed precondition or guard on a Tier 3 high-blast-radius operation. They are not synonyms, and a command needing both should expose both flags.

Can a CLI command prompt for confirmation in non-interactive mode?▼

No. Prompts are allowed only when stdin is a TTY via ClinkrInteraction.isInteractive(). Non-interactive invocations missing authorization must fail fast with a usageError whose data names the missing flag, never hang on a prompt.

When is raw exit allowed instead of the Clinkr result envelope?▼

Raw exit via rawCommand is sanctioned only when the command's core contract is a TUI, a streaming protocol, or process-control/third-party passthrough. Ordinary finite agent-facing commands must use the standard envelope, and even raw commands map backend failures to exit 2.

Related Skills

Explore More Software Engineering Skills→
t0labt0lab
2

stack-typescript

Load TypeScript/JavaScript coding rules from .claude/rules/stack-typescript/ before edits.

Official
Intermediate
gofhirgofhir
2

go-constructors

Demonstrate Go constructor patterns including functional options and builders.

Official
Intermediate
sertaoseracloudsertaoseracloud

documentation-and-adrs

Record architectural decisions and rationale in ADR templates.

Community
Advanced
siviter-xyzsiviter-xyz
21

cli-building

Design and implement async-first CLIs with modular commands.

Official
Advanced