Skip to main content
skill CX Codex

adding-a-command — Claude Code skill: what it does, how to install

adding-a-command generates Commander.js CLI commands in src/commands/, connects them to src/cli.ts, and sets up telemetry tracking.

MIT ★ 1,319 updated 2026-09-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add caliber-ai-org/ai-setup --skill adding-a-command -a claude-code
Open on GitHub

What adding-a-command does

This skill scaffolds CLI commands tailored to Caliber's Commander.js conventions. It writes a dedicated file inside src/commands/ with a named async export, explicit TypeScript interfaces for options, and console output formatted with chalk.

Next, it wires the new entry into src/cli.ts. Every action handler must be wrapped with tracked() so CLI usage streams telemetry automatically. User input errors throw new Error('__exit__') to avoid printing noisy stack traces in the terminal.

The skill strictly targets new command scaffolding. Its rules explicitly forbid modifying existing handlers or fixing bugs in current commands.

What it helps with

  • Scaffold a typed CLI handler file inside src/commands/
  • Register a command in src/cli.ts using the tracked() telemetry wrapper
  • Parse custom flag values like comma-separated arguments
  • Handle user errors cleanly with chalk and silent exit codes

Example prompts for the agent

  • Add a status command to show config state with a --json flag
  • Create a sources add subcommand that accepts a file path argument
  • Add an init command supporting comma-separated values in --agent

How to install adding-a-command

1Skills CLI (Vercel)

npx skills add caliber-ai-org/ai-setup --skill adding-a-command -a claude-code

2Manually: put the files in place

~/.claude/skills/adding-a-command/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adding-a-command/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about adding-a-command

How to install adding-a-command in Claude Code?

Run npx skills add caliber-ai-org/ai-setup --skill adding-a-command -a claude-code in your terminal.

What does adding-a-command do?

It creates boilerplate code for Commander.js CLI actions, registers them in src/cli.ts, and adds required telemetry wrappers.

Can it modify existing CLI commands?

No. The prompt guidelines explicitly prohibit modifying or debugging already implemented commands.

Source text

SKILL.md · MIT
---
name: adding-a-command
description: Creates a new CLI command following the Commander.js pattern in src/commands/. Handles command registration in src/cli.ts, telemetry tracking via tracked() wrapper, and option parsing. Use when user says add command, new CLI command, create subcommand, or adds files to src/commands/. Do NOT use for modifying existing commands or fixing bugs in existing commands.
paths:
  - src/commands/**/*.ts
  - src/cli.ts
---
# Adding a Command

## Critical

- **Export pattern**: Command must export a named async function: `export async function myCommand(options?: OptionType)`. Never use default exports.
- **Registration in cli.ts**: Every command must be imported and registered with `.command()` chain in `src/cli.ts`, wrapped with `tracked()` for telemetry.
- **Error signaling**: Use `throw new Error('__exit__')` to exit gracefully without printing the error message. Use chalk for user-facing messages.
- **Options typing**: Commands receiving options must define a TypeScript interface for those options. Pass options as a destructured object parameter.

## Instructions

1. **Create the command file** at `src/commands/{commandName}.ts` with named async export.
   - Signature: `export async function {commandName}Command(options?: { optionName?: optionType }) { ... }`
   - Import only what you need (avoid kitchen-sink imports).
   - Return void (handle all output via console.log or chalk).
   - Verify the file follows the naming convention: camelCase function + "Command" suffix.

2. **Handle errors consistently**: Wrap error-prone operations in try/catch. Distinguish between user errors and system errors:
   - User error (bad input): `console.error(chalk.red('message')); throw new Error('__exit__');`
   - System error (missing dependency): `throw new Error('Detailed error message');` — this will print and exit with code 1.
   - Parse-like errors: Use ora spinner with `.fail()` before throwing.
   - This step prevents double error printing in bin.ts.

3. **Import and register in src/cli.ts** in the correct location:
   - Add import at the top: `import { {commandName}Command } from './commands/{commandName}.js';`
   - Register the command in the appropriate section (main commands, or nested under a group like `sources`).
   - For main commands: `.command('{kebab-name}').description('...').option(...).action(tracked('{kebab-name}', {commandName}Command))`
   - For subcommands (like `sources add`): `sources.command('add').description(...).action(tracked('sources:add', sourcesAddCommand))`
   - Key: Wrap handler with `tracked('{command-name}', handler)` for automatic telemetry.
   - Verify the command name in tracked() uses kebab-case for main commands and colon-separated for subcommands.

4. **Define options (if needed)**:
   - Add `.option()` chains before `.action()`: `.option('--flag', 'Description')` or `.option('--opt <value>', 'Description')`
   - For parsed options (like comma-separated agents), add a parse function: `.option('--opt <value>', 'Description', parseFunction)`
   - Pass options to handler: `.action(tracked('name', (opts) => command(opts)))`
   - Define TypeScript interface for the options object.
   - Verify option names use camelCase (Commander converts kebab-case flags to camelCase).

5. **Verify before proceeding**:
   - Function exports correctly and is imported in cli.ts.
   - Command is registered with tracked() wrapper.
   - Output uses chalk for colors, not plain console.log.
   - Error paths throw `new Error('__exit__')` for user errors.

## Examples

### Example 1: Simple command (status)

User says: "Add a command to show config status"

**Actions taken**:
1. Create src/commands/status.ts with statusCommand() export
2. Import and register in src/cli.ts with tracked() wrapper

**Result**: `caliber status` displays config status; `caliber status --json` outputs JSON.

Code example:
```typescript
import chalk from 'chalk';
import { loadConfig } from '../llm/config.js';

export async function statusCommand(options?: { json?: boolean }) {
  const config = loadConfig();
  
  if (options?.json) {
    console.log(JSON.stringify({ configured: !!config }, null, 2));
    return;
  }
  
  console.log(chalk.bold('Status'));
  console.log(`  LLM: ${chalk.green(config?.provider || 'Not configured')}`);
}
```

Registration in src/cli.ts:
```typescript
import { statusCommand } from './commands/status.js';
program
  .command('status')
  .description('Show config status')
  .option('--json', 'Output as JSON')
  .action(tracked('status', statusCommand));
```

---

### Example 2: Subcommand with arguments

User says: "Add a sources add subcommand"

**Actions taken**:
1. Create src/commands/sources.ts with sourcesAddCommand() export
2. Register under sources group with tracked('sources:add', ...)

**Result**: `caliber sources add ../lib` adds a source.

Code example:
```typescript
export async function sourcesAddCommand(sourcePath: string) {
  if (!fs.existsSync(sourcePath)) {
    console.log(chalk.red(`Path not found: ${sourcePath}`));
    throw new Error('__exit__');
  }
  const existing = loadSourcesConfig(process.cwd());
  existing.push({ type: 'repo', path: sourcePath });
  writeSourcesConfig(process.cwd(), existing);
  console.log(chalk.green(`Added ${sourcePath}`));
}
```

Registration:
```typescript
const sources = program.command('sources');
sources
  .command('add')
  .argument('<path>', 'Path to add')
  .action(tracked('sources:add', sourcesAddCommand));
```

---

### Example 3: Command with option parsing

User says: "Add init with --agent flag supporting comma-separated values"

**Actions taken**:
1. Create parseAgentOption() parser in src/cli.ts
2. Create src/commands/init.ts with initCommand(options)
3. Register with custom parser

**Result**: `caliber init --agent claude,cursor` passes parsed array to handler.

Parser code:
```typescript
function parseAgentOption(value: string) {
  const agents = value.split(',').map(s => s.trim().toLowerCase());
  if (agents.length === 0) {
    console.error('Invalid agent');
    process.exit(1);
  }
  return agents;
}

program.command('init')
  .option('--agent <type>', 'Agents (comma-separated)', parseAgentOption)
  .action(tracked('init', initCommand));
```

## Common Issues

**Issue**: "SyntaxError: The requested module does not provide an export named 'myCommand'"
- **Cause**: Function not exported or exported as default instead of named.
- **Fix**: Use `export async function myCommand(...)` (not `export default`).

**Issue**: Command appears in help but crashes when run
- **Cause**: Handler not wrapped with `tracked()` or function import mismatch.
- **Fix**: Verify import name matches function export. Wrap with `tracked('command-name', handler)`.

**Issue**: "Error: __exit__" appears in output for user errors
- **Cause**: Throwing generic error instead of using error exit pattern.
- **Fix**: Use `console.error(chalk.red('message')); throw new Error('__exit__');` for user-facing errors.

**Issue**: --dry-run flag not recognized
- **Cause**: Option not declared with `.option()` or wrong camelCase in interface.
- **Fix**: Add `.option('--dry-run', 'Description')` and ensure options interface has `dryRun?: boolean`.

**Issue**: Subcommand crashes but parent command works
- **Cause**: Using `program.command()` instead of `groupVar.command()` for subcommands.
- **Fix**: Register on group: `const sources = program.command('sources'); sources.command('add')...`

**Issue**: Telemetry not appearing
- **Cause**: Handler not wrapped with `tracked()` or wrong command name.
- **Fix**: Ensure `.action(tracked('{kebab-case}', handler))` wraps handler. Use colon for subcommands like 'sources:add'.

**Issue**: "Cannot find module" with relative imports
- **Cause**: Using `.ts` extension in imports.
- **Fix**: Always use `.js` extension: `import { x } from '../lib/file.js'` (required for ESM).

© caliber-ai-org · MIT · caliber-ai-org/ai-setup

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set17

The whole set →
caliber-pre-commit caliber-pre-commit — a commit-time rule: it checks for the Caliber git hook and, when the hook is absent, syncs and stages your agent config files. CX Codex +1 ★ 1,319repo stars find-skills find-skills discovers community skills from the Caliber registry and installs them directly into your coding session. CX Codex +1 ★ 1,319repo stars save-learning save-learning turns a user's lasting preferences into project learnings. Use it when an agent should carry a rule from one session into the next. CX Codex +1 ★ 1,319repo stars setup-caliber setup-caliber walks a project through Caliber setup: installs the CLI, hooks agent config sync into every commit, and creates the config files your agents are missing. CX Codex +1 ★ 1,319repo stars llm-provider The llm-provider skill guides you through adding an LLM backend to a project, from its provider class to configuration and factory registration. Use it when connecting a third-party API or another model. CX Codex +1 ★ 1,319repo stars scoring-checks Adds deterministic scoring checks that measure AI agent config quality. Evaluates file structure, standards compliance, and configuration patterns — with no randomness or external calls. CX Codex +1 ★ 1,319repo stars caliber-testing caliber-testing is a Claude Code skill that generates Vitest tests with process.env resets, vi.hoisted mocks, and test files placed in __tests__ directories. CX Codex +1 ★ 1,319repo stars writers-pattern The writers-pattern skill guides you through adding a module that writes agent config files for a new platform. Use it when extending caliber to another coding tool. CX Codex +1 ★ 1,319repo stars

Project sponsors

Companies that keep this analytics open