Tooling Development

Not this skill: a user-facing service or endpoint (backend-systems), or CI pipeline steps (cloud-devops).

Preflight

cat package.json | jq '{bin, files, engines}'   # what actually ships
command -v <tool> && <tool> --help | head -20   # the current contract, if it exists

Write the invocation examples first — including the one inside a CI job and the one inside a pipe. They define the contract more honestly than a design document.

Workflow

1. Write the invocation examples first — including the one inside a CI job and the one inside a pipe. They define the contract more honestly than any design doc.
2. Inspect the repository's runtime, packaging, config, logging, and distribution conventions before adding a fourth way to do any of them.
3. Separate command parsing from domain logic. The core must be callable without a terminal, or it can never be tested or reused.
4. Support --help, non-interactive execution, machine-readable output, and bounded cancellation.
5. Test invalid flags, missing config, partial files, interruption, and cross-platform paths — not just the happy invocation.
6. Smoke the installed or packaged command, never only the source entry point. Packaging is where tools break.

The Stream Contract

This split is the entire reason a tool composes.

A single exit code 1 for everything makes automation impossible: the caller cannot tell "you typed it wrong" from "the network died". Argument parsing has its own edge cases (--, negative numbers, repeated flags, clustering) and exit codes need a versioning and deprecation story of their own — see argument and exit conventions.

Adapt to the Terminal, Then Get Out of the Way

const isTTY = process.stdout.isTTY;
const color = isTTY && !process.env.NO_COLOR && !argv.noColor;
// JSON when piped, human table when interactive
isTTY ? renderTable(rows) : process.stdout.write(JSON.stringify(rows) + '\n');

Honor NO_COLOR and an explicit --no-color regardless of TTY detection. Never emit a spinner or a progress bar into a redirected stream — it becomes megabytes of escape codes in a CI log.

Failure Paths People Skip

Config precedence, highest first: command flag → environment variable → project file → user file → built-in default. Print the resolved source on request; "why is it using that value" is the most common support question a tool generates — see argument and exit conventions for the diagnostic technique when precedence itself is the bug.

Reference Routing

• Practical tooling cases: real-world-cases.md
• CLI behavior and operational standards: tooling-best-practices.md
• Implementation patterns: tooling-examples.md
• Argument parsing, exit codes, and config precedence diagnosis: argument-and-exit-conventions.md
• Signals, atomic writes, TTY/piping, packaging, and flag deprecation: packaging-and-compatibility.md
• Reference docs generated from code or schemas: use the documentation skill.

See Reference Map for specialized references and sub-domain guides.

Stop

• The tool would prompt in a non-TTY context. Never prompt in CI; require an explicit flag.
• A partial output file would survive an interruption. Write to a temp path and rename atomically instead.
• Only the source entry point was smoked. Test the packaged command — packaging is where tools break.

Rules

• Hand off deployment pipelines to cloud-devops, testing to test-engineering, and agent tools to agent-engineering.
• A truncated artifact that looks complete is worse than no artifact. Write to a temp path and rename atomically on success.
• Never prompt in CI. Provide explicit flags for confirmation and for quiet mode.
• Avoid regex parsing when a structured parser exists — the regex works until the first quoted comma.
• Version the output format. A tool whose JSON shape drifts silently breaks every script built on it; --format-version or a schema field costs nothing now and everything later.
• --help is the primary documentation. If a behavior is not in it, the behavior does not exist for most users.
• Deprecate a flag by keeping it working, warning on stderr with the replacement, and removing it only after a documented version window — never a silent break; Hunt & Thomas's The Pragmatic Programmer frames this as treating your own CLI contract with the same reversibility discipline as an external API.
• Name commands and flags for what they do, not how they are implemented — Robert C. Martin's Clean Code naming rules apply as much to a --flag as to a function.
• Shell scripts and one-off command safety belong to cloud-devops; publishing and versioning the tool to git-workflow.

Checklist

• Invocation examples written first, including the CI and piped cases.
• Core logic callable without a terminal.
• stdout carries only the result; diagnostic output on stderr; exit codes distinguish usage from runtime failure.
• TTY detection, NO_COLOR, signals, and EPIPE all handled.
• Config precedence documented and inspectable.
• Partial output never left behind; the packaged command smoke-tested.