ahmadawais/clack

Clack CLI Skill

Use this skill to implement reliable interactive CLIs with @clack/core and @clack/prompts.

Workflow

1. Decide whether to use @clack/prompts or @clack/core.
2. Read only the minimum reference files needed for the task.
3. Start from the closest example in references/examples/.
4. Implement cancellation handling after every prompt.
5. Add UX polish (intro, outro, spinner, progress, tasks, log, taskLog, stream) when useful.
6. Verify imports against export maps in references/docs/prompts-exports.ts and references/docs/core-exports.ts.

Pick the Right Layer

Use @clack/prompts by default.

• Choose it for production-ready styling and quick delivery.
• Use it when the request maps to standard prompt types: text, confirm, select, multiselect, grouped prompts, logs, spinners, progress, tasks, or streaming logs.

Use @clack/core when lower-level control is required.

• Choose it for custom rendering, custom prompt behavior, or unstyled primitives.
• Use it when the request needs direct prompt classes (TextPrompt, SelectPrompt, ConfirmPrompt, Prompt) or deep customization.

Mandatory Safety Patterns

Handle cancellation on every prompt result.

import * as p from '@clack/prompts';

const value = await p.text({ message: 'Your name?' });
if (p.isCancel(value)) {
  p.cancel('Operation cancelled.');
  process.exit(0);
}

Start and close sessions cleanly for user-facing CLIs.

p.intro('create-app');
// prompts
p.outro('Done');

Prompt Design Guidance

Use these defaults unless the user asks otherwise.

• text: provide validate for required or constrained input.
• confirm: use for binary decisions; avoid coercing free-form text.
• select: use for mutually exclusive choices.
• multiselect or groupMultiselect: use for multi-choice and hierarchical multi-choice flows.
• group: gather structured answers while preserving dependencies between steps.
• spinner and progress: wrap long-running tasks and update status clearly.
• tasks: execute sequential task blocks with spinner status.
• taskLog: stream subprocess output and finish with success/failure.
• stream: render async or tokenized output (for LLM-style streaming).

Implementation Sequence

1. Inspect user requirements and identify required prompt primitives.
2. Read the nearest example under references/examples/.
3. Confirm function/class availability from:
   • references/docs/prompts-exports.ts
   • references/docs/core-exports.ts
4. If behavior is unclear, inspect source under:
   • references/source/prompts/
   • references/source/core/
5. Implement with cancellation guards and clear terminal messaging.
6. Keep fallback behavior for non-interactive contexts when requested (see spinner and CI-oriented examples).

Reference Loading Strategy

Start with these files.

• references/docs/prompts-readme.md
• references/docs/core-readme.md
• references/INDEX.md

Load specific source files only as needed.

• Prompts wrapper internals: references/source/prompts/*.ts
• Core prompt primitives: references/source/core/prompts/*.ts
• Core utility behavior: references/source/core/utils/*.ts

Example-First Mapping

Use this quick mapping to avoid re-inventing flows.

• General prompt suite: references/examples/basic/index.ts
• Validation: references/examples/basic/text-validation.ts
• Autocomplete: references/examples/basic/autocomplete.ts
• Autocomplete multi-select: references/examples/basic/autocomplete-multiselect.ts
• Defaults: references/examples/basic/default-value.ts
• Filesystem path prompt: references/examples/basic/path.ts
• Spinner basics: references/examples/basic/spinner.ts
• Spinner cancellation: references/examples/basic/spinner-cancel.ts
• Advanced spinner cancellation: references/examples/basic/spinner-cancel-advanced.ts
• CI-oriented spinner behavior: references/examples/basic/spinner-ci.ts
• Timer-style spinner updates: references/examples/basic/spinner-timer.ts
• Progress bar: references/examples/basic/progress.ts
• Task log streaming: references/examples/basic/task-log.ts
• Stream utility: references/examples/basic/stream.ts
• Changesets integration flow: references/examples/changesets/index.ts

Quality Bar

Before finalizing any clack implementation:

• Confirm every import exists in the current exports file.
• Ensure cancellation flow always exits safely.
• Ensure prompt wording is short and unambiguous.
• Ensure long-running operations provide visible status.
• Ensure selected layer (core vs prompts) matches customization needs.