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/spec.md

View on GitHub
# Carapace User Spec Creation Guide

Create shell completion specs for [carapace](https://carapace.sh) using YAML files.

## Location

User specs stored in: `${UserConfigDir}/carapace/specs/`

| OS | Path |
|----|------|
| Linux | `~/.config/carapace/specs/` |
| macOS | `~/Library/Application Support/carapace/specs/` |
| Windows | `%APPDATA%\carapace\specs\` |

> Filename must match spec name (e.g., `mycmd.yaml` for `name: mycmd`)

## Schema

Add to top of spec file for schema validation:

```yaml
# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
```

## Basic Structure

```yaml
name: mycmd
aliases: [myc, mycmd-alias]
description: My command description
group: Some Group
hidden: false
parsing: interspersed
flags:
  -v, --verbose: be verbose
  -f, --file=: input file
persistentflags:
  --help: show help
commands:
  - name: sub
    description: subcommand
    flags:
      -x: exclusive flag
```

> `name` may embed a usage string after the command name (e.g. `name: usage [-F file | -D dir]... [-f format] profile`). The command name for filename matching is taken up to the first space, so `usage ... profile` maps to the file `usage.yaml`.

## Flags

### Modifier Suffixes

| Suffix | Meaning | Example |
|--------|---------|---------|
| `=` | takes argument | `--file=` |
| `*` | repeatable | `--tag*` |
| `?` | optional argument | `--output?` |
| `&` | hidden | `--secret&` |
| `!` | required | `--config!` |

```yaml
flags:
  -b: bool flag (no suffix)
  -v=: shorthand with value
  --repeatable*: repeatable flag
  -o, --optarg?: shorthand + optional arg
  --hidden&: hidden flag
  --required!: required flag
```

### Extended Format

For `nargs` or `default`, use object syntax:

```yaml
flags:
  --two-args=: {description: consumes two args, nargs: 2}
  --any-args=: {description: consumes multiple, nargs: -1}
  --default-value=: {description: flag with default value, default: /tmp/out.txt}
```

> Generated specs only use the object notation when `nargs` is set or `default` has a non-zero value; for zero-value defaults the plain string form is emitted.

### Exclusive Flags

`exclusiveflags` declares mutually exclusive flag groups (list of lists of flag names):

```yaml
exclusiveflags:
  - [verbose, quiet]
  - [json, yaml]
```

Flags referenced here must be defined in `flags` or `persistentflags` of the same command.

### Non-POSIX Shorthands

When built with carapace-pflag:

```yaml
flags:
  -single: non-posix shorthand
  -short, -long: both shorthand
```

> For the Go API (`SetPrefix`, `ArgumentStyle`, `Mode`), see [references/integrate.md](integrate.md).

## Parsing Modes

| Mode | Behavior |
|------|----------|
| `interspersed` | mixed flags and positional arguments (default) |
| `non-interspersed` | first positional stops flag parsing |
| `disabled` | no flag parsing (use for bridged completions) |

```yaml
parsing: disabled  # required for bridge macros
```

## Completion

### Flag Completion

```yaml
completion:
  flag:
    file: ["$files"]
    verbose: ["true", "false"]
```

### Positional Completion

```yaml
completion:
  positional:
    - ["$directories"]           # first positional
    - ["$executables"]           # second positional
  positionalany: ["$files"]      # all remaining positions
```

### Dash Completion (for flag-like args)

```yaml
completion:
  dash:
    - ["-a", "--alpha"]
    - ["-b", "--beta"]
  dashany: ["-x", "--xxx"]
```

## Documentation

```yaml
documentation:
  command: "Main command description"
  flag:
    file: "Input file path"
  positional:
    - "First argument: source"
    - "Second argument: destination"
  positionalany: "Additional files"
  dash:
    - "Short option"
    - "Long option"
  dashany: "Additional options"
```

## Macros

Macros are `$`-prefixed completion actions used in completion arrays. For full details on macro types, formatting, and how to look up available macros, see the **references/macro.md** skill. To convert a spec to a native Go completer, see the **references/convert.md** skill.

### Quick Reference

```yaml
completion:
  positional:
    - ["$directories"]
    - ["$files([.go, .mod])"]
    - ["$carapace.tools.git.Refs({tags: true})"]
```

### Executing Commands

```yaml
run: "$sh(echo one; echo two)"
run: "$bash(echo -e 'one\\ntwo')"
run: "$pwsh(echo one`ntwo)"
```

## Modifiers

Change completion behavior with ` ||| ` delimiter. For full modifier reference, see the **references/macro.md** skill.

```yaml
# Generic: apply to all values
["$files", "$chdir(/tmp)"]

# Specific: apply to preceding value only
["$files ||| $chdir(/tmp)"]
```

## Values Format

Values support description and style with `\t` delimiter:

```yaml
["value", "value\tdescription", "value\tdescription\tblue"]
```

Styles can be combined using space as delimiter (adopted from Elvish):

```yaml
["value\tdescription\tblue underlined"]
```

### Foreground Colors

`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bright-*`

### Background Colors

Use `bg-` prefix: `bg-black`, `bg-red`, `bg-green`, `bg-yellow`, `bg-blue`, `bg-magenta`, `bg-cyan`, `bg-white`, `bg-bright-*`

### Extended Colors

- **XTerm 256**: `color<0-255>` (e.g., `color123`)
- **True Color (Hex)**: `#RRGGBB` (e.g., `#ff0000`)

### Attributes

`bold`, `dim`, `italic`, `underlined`, `blink`, `inverse`, `default`, `fg-default`, `bg-default`

### Negation/Toggle

`no-<attr>` (e.g., `no-bold`), `toggle-<attr>` (e.g., `toggle-italic`)

## Runnable Specs

Specs with `run` field become executable via shims.

### Alias (Command Array)

Aliases retain existing completion unless otherwise defined.

```yaml
name: gh-issues
run: ["gh", "issue", "--repo", "${REPO}"]
```

### Script (Macro with Environment Substitution)

```yaml
name: ls-remote
run: "$(git ls-remote --sort='${C_FLAG_SORT:-HEAD}' $@)"
flags:
  --sort=: field to sort on
completion:
  positionalany: ["$carapace.tools.git.LsRemoteRefs({url: '${C_ARG0}'})"]
```

> For macro formatting details, see the **references/macro.md** skill.

### Shebang (Bash Script)

```yaml
name: myscript
run: |
  #!/usr/bin/env bash -x
  for arg in "$@"; do
    echo "${!arg}${C_FLAG_SUFFIX:-.suffix}"
  done
flags:
  -s, --suffix=: suffix to add
completion:
  positionalany: [one, two]
```

## Environment Variables

Variables replaced via `drone/envsubst`:

| Variable | Content |
|----------|---------|
| `${C_FLAG_<NAME>}` | flag value |
| `${C_ARG<n>}` | positional argument (0-indexed) |
| `${C_VALUE}` | current word being completed |
| `${C_PART<n>}` | parts during multipart completion |

### Defaults

```yaml
${C_FLAG_VERBOSE:-false}    # default if not set
${C_FLAG_SUFFIX//,/, }      # string replacement
```

## Example

```yaml
# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: mytool
description: My custom tool
group: Development
parsing: interspersed
flags:
  -v, --verbose: verbose output
  --quiet: quiet output
  -f, --file=!: input file
  --format=: output format
persistentflags:
  --help: show help
exclusiveflags:
  - [verbose, quiet]
completion:
  flag:
    file: ["$files([.txt, .md])"]
    format: ["json\tJavaScript Object Notation\tblue underlined", "yaml\thuman-readable data serialization", "xml"]
  positional:
   - ["$files"]
documentation:
  command: "My tool does something useful"
  flag:
    file: "Path to input file (required)"
    format: "Output format (default: json)"
```

## Bridging External Completions

Use `parsing: disabled` and bridge macro:

```yaml
name: kubectl
description: Kubernetes CLI
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.CarapaceBin([kubectl])"]
```

> For macro formatting details, see the **references/macro.md** skill.

- Generic bridge: `CarapaceBin`.
- Framework bridges: `Argcomplete`, `ArgcompleteV1`, `Aws`, `Bash`, `Carapace`, `CarapaceBin`, `Clap`, `Click`, `Cobra`, `Complete`, `Fish`, `Gcloud`, `Inshellisense`, `JJ`, `Kingpin`, `Kitten`, `Macro`, `Powershell`, `Typer`, `Urfavecli`, `UrfavecliV1`, `Yargs`, `Zsh`.

## Testing

```bash
source <(carapace _carapace bash)   # reload specs (adjust shell name)
```

> For macro lookup and formatting, see the **references/macro.md** skill.
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