К основному содержанию
скилл CX Codex

adding-a-command — скилл для Claude Code: что делает и как установить

Скилл adding-a-command создаёт новые CLI-команды на Commander.js в src/commands/, подключает их к src/cli.ts и настраивает сбор телеметрии.

MIT ★ 1 319 обновлён 2026-09-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add caliber-ai-org/ai-setup --skill adding-a-command -a claude-code
Открыть на GitHub

Что делает adding-a-command

Скилл формирует файлы команд по структуре проекта Caliber. Каждый файл в каталоге src/commands/ получает именованный асинхронный экспорт вида export async function {commandName}Command(...), интерфейс для входных опций TypeScript и форматирование вывода через chalk.

Затем ассистент регистрирует команду в цепочке src/cli.ts. Главное требование шаблона — обёртка обработчика вызовом tracked(), через который собирается телеметрия по событиям CLI. Для ошибок пользователя используется тихий выход через throw new Error('__exit__'), чтобы исключить дублирование стека в терминале.

Скилл рассчитан строго на создание новых файлов: инструкция запрещает запускать его для правок или отладки уже готовых команд.

Какие задачи решает

  • Создать TypeScript-обработчик новой команды в src/commands/
  • Зарегистрировать вызов в src/cli.ts с обёрткой телеметрии tracked()
  • Описать интерфейсы опций и парсеры флагов для Commander.js
  • Разграничить системные сбои и пользовательские ошибки с выходом __exit__

Примеры запросов агенту

  • Добавь команду status для проверки конфигурации с флагом --json
  • Создай подкоманду sources add с аргументом пути к репозиторию
  • Добавь команду init с парсингом флага --agent через запятую

Как установить adding-a-command

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/adding-a-command/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об adding-a-command

Как установить adding-a-command в Claude Code?

Выполните команду npx skills add caliber-ai-org/ai-setup --skill adding-a-command -a claude-code в терминале проекта.

Что делает этот скилл?

Он автоматизирует шаблонное добавление консольных команд на Commander.js: создаёт отдельный модуль, прописывает парсинг аргументов и связывает его с точкой входа src/cli.ts.

Можно ли обновлять им существующие команды?

Нет. Правила скилла прямо запрещают модифицировать готовые команды или чинить в них ошибки, разрешая только создание новых.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
cli-to-js-api-wrapper reason-machines Скилл cli-to-js-api-wrapper для Claude Code объясняет, как обернуть консольную утилиту в типизированный JavaScript/TypeScript API через cli-to-js. Агент вызывает методы вместо склейки строк. CX Codex +1 446установок adding-docker spencerpauly Скилл adding-docker для Claude Code добавляет в проект Dockerfile, docker-compose и .dockerignore. Упаковывает приложение в контейнер без ручной возни с конфигами. CX Codex +1 438установок adding-auth spencerpauly Скилл adding-auth проводит агента по шагам добавления аутентификации в веб-приложение на NextAuth.js: провайдеры OAuth, сессии и защищённые маршруты. CX Codex +1 417установок linear-sdk-scripting cline Скилл linear-sdk-scripting для Claude Code и других AI-кодеров: управляет Linear через Node-скрипты с официальным SDK @linear/sdk без MCP-сервера — читает, создаёт и обновляет задачи, проекты, комментарии и метаданные. CX Codex +1 1 400установок codex-theme-finder codexthemes Скилл codex-theme-finder ищет опубликованные темы на codexthemes.ai прямо из чата с агентом. Работает анонимно по бесплатному лимиту или с личным ключом API. CX Codex +1 241установок web-search AnswerZhao Скилл web-search помогает настроить поиск в интернете через библиотеку z-ai-web-dev-sdk или утилиту z-ai CLI, возвращая ссылки, сниппеты и даты страниц. CX Codex +1 101установок

Из того же набора17

Весь набор →
caliber-pre-commit Правило caliber-pre-commit на каждый коммит: проверяет хук Caliber и, если хука нет, синхронизирует конфиги агентов и добавляет их в индекс. CX Codex +1 ★ 1 319звёзд репо find-skills Скилл find-skills ищет готовые скиллы сообщества через реестр Caliber и подключает их прямо во время диалога с агентом. CX Codex +1 ★ 1 319звёзд репо save-learning Скилл save-learning сохраняет правила и предпочтения пользователя для следующих сессий проекта. Он пригодится, когда вы хотите, чтобы агент помнил договорённости между запусками. CX Codex +1 ★ 1 319звёзд репо setup-caliber Скилл setup-caliber доводит проект до рабочего Caliber: ставит CLI, включает синхронизацию конфигов агентов на коммите и создаёт недостающие файлы. CX Codex +1 ★ 1 319звёзд репо llm-provider Скилл llm-provider для Claude Code помогает добавить в проект новый бэкенд LLM — от класса провайдера до регистрации в конфигурации и фабрике. CX Codex +1 ★ 1 319звёзд репо scoring-checks Скилл scoring-checks добавляет детерминированные проверки качества конфигурации AI-агента. Оценивает структуру, наличие файлов и соответствие стандартам — без случайности и внешних запросов. CX Codex +1 ★ 1 319звёзд репо caliber-testing Скилл caliber-testing для Claude Code генерирует тесты Vitest с изоляцией переменных среды, моками через vi.hoisted и размещением файлов в каталогах __tests__. CX Codex +1 ★ 1 319звёзд репо writers-pattern Скилл writers-pattern описывает, как добавить модуль, который записывает конфиги агента для новой платформы. Пригодится при расширении поддержки инструментов в caliber. CX Codex +1 ★ 1 319звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой