Skip to content

carapace-sh/carapace-bin / skills/carapace

carapace

Verified

Use when working with carapace shell completion — integrating into CLIs, writing YAML specs, creating custom actions, building completion-aware lexers for DSLs, looking up macros, setting up shell completion, configuring choices/bridges, using the MCP server, or adding man page documentation.

FileKindSize
SKILL.mdskill md4.0 KB
references/action.mdmarkdown20.8 KB
references/choice.mdmarkdown9.0 KB
references/convert.mdmarkdown10.5 KB
references/env.mdmarkdown7.8 KB
references/integrate.mdmarkdown29.1 KB
references/lexer.mdmarkdown24.3 KB
references/macro.mdmarkdown19.4 KB
references/man.mdmarkdown13.5 KB
references/mcp.mdmarkdown14.0 KB
references/scrape.mdmarkdown6.3 KB
references/setup.mdmarkdown6.8 KB
references/spec.mdmarkdown8.0 KB
references/update.mdmarkdown11.2 KB

references/update.md

View on GitHub
# Incremental Completer Update Guide

Update an **existing** Go completer when a new version of the CLI tool adds, removes, or changes flags and subcommands. This is the most common real-world scenario — distinct from [references/convert.md](convert.md) which covers creating a completer from scratch.

## Overview

The workflow has three phases:

1. **Generate reference** — scrape the new spec and generate a cobra skeleton for comparison
2. **Identify changes** — diff the skeleton against the existing completer to find exactly what changed
3. **Apply surgically** — edit existing files to apply only the structural changes, preserving all custom completion logic

**The golden rule**: never bulk-copy codegen output over existing files. Codegen only emits what the spec encodes — completion actions and completer-specific imports are always lost, and group info survives only if the spec defines `group` fields. Always apply changes surgically to existing files.

## Step 1: Scrape the New Spec

Generate a YAML spec from the new version of the CLI tool. See [references/scrape.md](scrape.md) for the full scraping workflow.

```bash
# If a scraper exists in the scrape project
docker build -t scrape-<tool> -f scrapers/<tool>/Dockerfile --build-arg VERSION=v1.2.3 scrapers/<tool>/
docker run --rm scrape-<tool> > /tmp/<tool>-spec.yaml
```

If no scraper exists and the tool uses cobra, you can also get a spec from the built binary:

```bash
carapace <tool> spec > /tmp/<tool>-spec.yaml
```

## Step 2: Generate Codegen Reference

Use the MCP `codegen` tool or the CLI equivalent to generate a cobra command skeleton from the spec:

```bash
# CLI
carapace --codegen /tmp/<tool>-spec.yaml

# MCP tool (returns list of generated filenames in /tmp/carapace-codegen-<hash>/)
mcp_carapace_codegen(path="/tmp/<tool>-spec.yaml")
```

The generated files contain:
- Cobra command structs (`Use`, `Short`, `GroupID`, `Aliases`, `Hidden`)
- Flag registrations (type, shorthand, description, default value)
- Flag extras where applicable: `NoOptDefVal` (optional-argument flags), `Hidden = true`, and `MarkFlagRequired` calls — these don't appear as plain flag-registration lines
- Group definitions (`AddGroup`) — only when the spec defines groups
- Subcommand wiring (`AddCommand`)
- `Standalone()` calls
- A root-level `func Execute()`

The generated files do **not** contain:
- `FlagCompletion`, `PositionalCompletion`, `PositionalAnyCompletion` — all completion actions are stripped
- Completer-specific imports (only `carapace` and `cobra`)
- Completer-specific `cmd/action/` packages

**This is a reference only.** The codegen output lives in `/tmp/carapace-codegen-<hash>/` and should never be copied directly into the completer directory.

## Step 3: Identify Structural Changes

Compare the codegen output to the existing completer to find exactly what changed. The categories of change are:

| Category | What to look for |
|----------|-----------------|
| New subcommands | Files in codegen that don't exist in the completer |
| Removed subcommands | Files in the completer that don't exist in codegen |
| New flags | Flag registrations in codegen not present in the completer |
| Removed flags | Flag registrations in the completer not present in codegen |
| Changed flag types | `String` → `StringSlice`, `Bool` → `BoolP`, etc. |
| Changed descriptions | One-line `Short` or flag description differs |
| New groups | `AddGroup` calls in codegen not present in the completer |

### Semi-automated diff script

```bash
CODEGEN_DIR=/tmp/carapace-codegen-XXXXXX
COMPLETER_DIR=completers/common/<tool>_completer/cmd

for f in "$CODEGEN_DIR"/*.go; do
    name=$(basename "$f")
    existing="$COMPLETER_DIR/$name"
    if [ ! -f "$existing" ]; then
        echo "NEW SUBCOMMAND: $name"
    else
        # Diff only the flag and structural sections (skip completion wiring)
        diff <(grep -E '^\t\S+Cmd\.|\.Flags\(\)|\.AddCommand|AddGroup|carapace\.Gen' "$f") \
             <(grep -E '^\t\S+Cmd\.|\.Flags\(\)|\.AddCommand|AddGroup|carapace\.Gen' "$existing") \
             && true
    fi
done

for f in "$COMPLETER_DIR"/*.go; do
    name=$(basename "$f")
    if [ ! -f "$CODEGEN_DIR/$name" ]; then
        echo "REMOVED SUBCOMMAND: $name"
    fi
done
```

### What to compare manually

The script above catches structural changes. Also check:

- **Flag descriptions** — codegen uses descriptions from the spec, which may differ from the completer's current descriptions. Run a broader diff and look for description changes.
- **Flag types** — a `String` → `StringSlice` change is a type change, not just a description change. Look for different `.Flags().*()` method calls.
- **Shorthand changes** — a flag gaining or losing a shorthand (e.g. `Bool` → `BoolP`).

## Step 4: Apply Changes Surgically

For each category of change, apply the minimal edit to the existing file.

### New flag

Insert the flag registration in the `init()` function, maintaining alphabetical order within the contiguous flag block. Also add the flag to the `FlagCompletion` map if it has a custom completion action.

```go
// Before (attach.go)
attachCmd.Flags().BoolP("stdin", "i", false, "Pass stdin to the container")

// After — new --detach-keys flag inserted alphabetically before --stdin
attachCmd.Flags().String("detach-keys", "", "Override the key sequence for detaching a container")
attachCmd.Flags().BoolP("stdin", "i", false, "Pass stdin to the container")
```

If the new flag has a known completion action, add it to the `FlagCompletion` map:

```go
carapace.Gen(attachCmd).FlagCompletion(carapace.ActionMap{
    "detach-keys": action.ActionDetachKeys(),
    "stdin":       carapace.ActionValues("true", "false"),
})
```

### Removed flag

Delete the flag registration line and its entry in the `FlagCompletion` map (if present). Removing a flag is rare but happens when upstream deprecates and removes an option.

### Changed flag type

Replace the flag registration call. Update the `FlagCompletion` entry if the type change affects completion (e.g. `String` → `StringSlice` may need `ActionValues` split on comma).

```go
// Before
waitCmd.Flags().String("for", "", "The condition to wait on")

// After — type changed from String to StringSlice
waitCmd.Flags().StringSlice("for", nil, "The condition to wait on")
```

### Changed description

Update only the description string. Do not touch the flag type, default value, or completion wiring.

```go
// Before
debugCmd.Flags().String("profile", "", "Legacy profiling mode")
// After
debugCmd.Flags().String("profile", "", "Profiling mode. Defaults to general")
```

### New subcommand

Create a new `.go` file following the existing completer's conventions. Use the codegen output as a starting point for the structure, then add completion wiring. The file must:

1. Declare the cobra command variable
2. Call `carapace.Gen(cmd).Standalone()` in `init()`
3. Define flags (alphabetically ordered)
4. Register with the parent command via `parentCmd.AddCommand(cmd)`
5. Add completion wiring (`FlagCompletion`, `PositionalCompletion`, etc.)

```go
package cmd

import (
    "github.com/carapace-sh/carapace"
    "github.com/spf13/cobra"
)

var kubercCmd = &cobra.Command{
    Use:   "kuberc",
    Short: "Manage kuberc configuration",
    GroupID: "management",
}

func init() {
    carapace.Gen(kubercCmd).Standalone()

    rootCmd.AddCommand(kubercCmd)
}
```

Check the codegen output for the correct `GroupID` value — the skeleton will have it if the spec defines groups.

### Removed subcommand

Delete the `.go` file and remove any references to the command variable from the parent's `AddCommand` call. Also remove any `cmd/action/` files that were specific to this subcommand.

### Subcommand promoted (moved in the tree)

When a subcommand moves (e.g. `alpha kuberc` → `kuberc`), this is both a removal and an addition:

1. Create the new file at the new location in the command tree
2. Copy over completion wiring from the old file, adjusting the parent command reference
3. Delete the old file
4. Update the old parent's `AddCommand` (remove the old reference) and the new parent's `AddCommand` (add the new reference)

### New flags on promoted subcommands

When a promoted subcommand also gains new flags, combine the operations: create the new file with the old completion wiring plus the new flags.

## Step 5: Update Man Docs

Use `carapace-man update` to refresh the spec structure in the man YAML files while preserving existing documentation:

```bash
# One-step update: generate spec, split with doc preservation, show diff
carapace-man update /tmp/<tool>-spec.yaml man/cmd/<tool>
```

This preserves all existing `documentation.command` and `documentation.flag` entries. It creates new files for new subcommands but does **not** delete files for removed subcommands.

After running `update`:

1. **Delete removed subcommand files** — manually remove YAML files for subcommands that no longer exist
2. **Add `documentation.command` entries** — for new subcommands and any existing ones missing docs. See [references/man.md](man.md) for standards.
3. **Review `documentation.flag` entries** — new flags may need flag docs if their short description is insufficient

## Step 6: Build, Lint, Test

```bash
# Build with all platform completers
go build -tags force_all -o /tmp/carapace-test ./cmd/carapace

# Lint (requires golangci-lint built via `golangci-lint custom`)
./custom-gcl run ./...

# Auto-fix ordering and duplicate findings if needed
./custom-gcl run --fix ./...

# Test completion output
/tmp/carapace-test <tool> bash ''
/tmp/carapace-test <tool> bash '--flag '

# Run test suite
go test -v ./cmd/...
```

**Important**: The MCP `complete_command` tool uses the installed binary, not the freshly built one. Always test with the built binary directly.

## Anti-Patterns

| Anti-pattern | Why it fails |
|-------------|-------------|
| **Bulk-copying codegen output over existing files** | Strips all GroupIDs, completion actions, completer-specific imports, and `cmd/action/` references. Restoring them manually across 80+ files is extremely fragile. |
| **Regex-based merge scripts** | Go code has too much structural variation for regex merges to handle reliably — brace nesting, import grouping, and init() ordering all break easily. |
| **Using MCP `complete_command` before rebuilding** | The MCP server runs the installed binary, not your local build. Completion output will be stale until you build and install. |
| **Editing without reading the exact context first** | The `edit` tool requires exact string matching. Whitespace, indentation, and blank lines must match precisely. Always `view` the target lines before editing. |

## Relationship to Other Skills

| Skill | When to use instead of this skill |
|-------|----------------------------------|
| **references/convert.md** | Creating a completer from scratch (no existing completer exists) |
| **references/scrape.md** | Generating the YAML spec — the step before this workflow |
| **references/spec.md** | Writing YAML user specs (the source format) |
| **references/macro.md** | Looking up macro signatures and formatting macro arguments |
| **references/action.md** | Creating/modifying Go actions that become macros |
| **references/man.md** | Man page documentation format, `carapace-man` workflow, `documentation.command`/`documentation.flag` guidelines |
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall