carapace-sh/carapace-bin / skills/carapace
carapace
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/action.md | markdown | 20.8 KB |
| references/choice.md | markdown | 9.0 KB |
| references/convert.md | markdown | 10.5 KB |
| references/env.md | markdown | 7.8 KB |
| references/integrate.md | markdown | 29.1 KB |
| references/lexer.md | markdown | 24.3 KB |
| references/macro.md | markdown | 19.4 KB |
| references/man.md | markdown | 13.5 KB |
| references/mcp.md | markdown | 14.0 KB |
| references/scrape.md | markdown | 6.3 KB |
| references/setup.md | markdown | 6.8 KB |
| references/spec.md | markdown | 8.0 KB |
| references/update.md | markdown | 11.2 KB |
references/convert.md
View on GitHub# Carapace Spec-to-Go Conversion Guide
Convert a carapace YAML user spec into a native Go completer that can be built into [carapace-bin](https://github.com/carapace-sh/carapace-bin).
## Overview
Conversion has two phases:
1. **Codegen** — generate the cobra command skeleton (flags, subcommands, groups) from the YAML spec
2. **Completion wiring** — manually translate the `completion` section into Go action code
The codegen tool does **not** produce completion code — it only generates the command structure. The `completion` section of the spec must be translated by hand using the macro and modifier mappings below.
## Step 1: Codegen
Use the carapace MCP `codegen` tool or the CLI equivalent:
```bash
carapace --codegen path/to/spec.yaml
```
This produces one or more `.go` files in a temp directory containing:
- Package declaration (`package cmd`)
- Cobra command structs (`Use`, `Short`, `GroupID`, `Aliases`, `Hidden`)
- Flag registrations (`String`, `Bool`, `CountP`, etc.)
- `Execute()` function (root command only)
- Subcommand wiring (`AddCommand`)
Copy the generated files into the carapace-bin completer directory (e.g. `cmd/traverse/`).
> The codegen `init()` already includes `carapace.Gen(rootCmd).Standalone()` — no need to add it manually.
## Step 2: Translate Completion Actions
Add `FlagCompletion`, `PositionalCompletion`, and/or `PositionalAnyCompletion` calls to `init()`. The mappings below translate YAML spec macros and modifiers to their Go equivalents.
### Core Action Macros
| YAML Macro | Go Equivalent |
|-----------|---------------|
| `$files` | `carapace.ActionFiles()` |
| `$files([.ext])` | `carapace.ActionFiles(".ext")` |
| `$directories` | `carapace.ActionDirectories()` |
| `$executables` | `carapace.ActionExecutables()` |
| `$message(text)` | `carapace.ActionMessage("text")` |
| `$values` | `carapace.ActionValues(...)` |
| `$valuesdescribed` | `carapace.ActionValuesDescribed(...)` |
### External Action Macros
External macros (prefixed with `carapace.`) reference actions from carapace-bin packages. Use the `list_macros` MCP tool or `carapace --macro` to find the Go import path and function name.
| YAML Macro | Go Equivalent |
|-----------|---------------|
| `$carapace.tools.git.Refs({tags: true})` | `git.ActionRefs(g.RefsOpts{Tags: true})` |
| `$carapace.tools.git.Tags` | `git.ActionTags()` |
| `$carapace.os.Users` | `os.ActionUsers()` |
Import the package from the `reference` field in the macro listing (e.g. `github.com/carapace-sh/carapace-bin/pkg/actions/tools/git`).
### Modifier Macros
Modifiers are applied to the preceding action using the `|||` delimiter in specs (generic modifier) or by chaining method calls in Go.
| YAML Modifier | Go Equivalent | Notes |
|--------------|---------------|-------|
| `$chdir(path)` | `.Chdir("path")` | Change to literal directory |
| `$chdir($traverse_macro)` | `.ChdirF(traverse.Xxx)` | See traverse mapping below |
| `$filter(pattern...)` | `.Filter(pattern...)` | |
| `$filterargs` | `.FilterArgs()` | |
| `$list(separator)` | `.List(separator)` | |
| `$multiparts(chars...)` | `.MultiParts(chars...)` | |
| `$nospace(chars)` | `.NoSpace(chars...)` | |
| `$noprefix(prefix)` | `.NoPrefix(prefix)` | Prevent common-prefix insertion (for given prefixes, or all) |
| `$prefix(prefix)` | `.Prefix(prefix)` | |
| `$retain(pattern...)` | `.Retain(pattern...)` | |
| `$shift(n)` | `.Shift(n)` | |
| `$split` | `.Split()` | |
| `$splitp` | `.SplitP()` | |
| `$suffix(suffix)` | `.Suffix(suffix)` | |
| `$suppress(pattern)` | `.Suppress(pattern)` | |
| `$style(style)` | `.Style(style)` | |
| `$tag(tag)` | `.Tag(tag)` | |
| `$uniquelist(separator)` | `.UniqueList(separator)` | |
| `$usage(text)` | `.Usage(text)` | |
### Traverse Macros
Inside `$chdir()`, the argument can be a traverse macro that resolves a directory at runtime. These map directly to functions in `github.com/carapace-sh/carapace/pkg/traverse`.
| YAML Macro | Go Equivalent | Resolves to |
|-----------|---------------|-------------|
| `$chdir($gitdir)` | `.ChdirF(traverse.GitDir)` | `GIT_DIR` env or `.git` dir |
| `$chdir($gitworktree)` | `.ChdirF(traverse.GitWorkTree)` | `GIT_WORK_TREE` env or parent of `.git` |
| `$chdir($parent([name1, name2]))` | `.ChdirF(traverse.Parent("name1", "name2"))` | Walks upward to find dir containing named files |
| `$chdir($tempdir)` | `.ChdirF(traverse.TempDir)` | `os.TempDir()` |
| `$chdir($usercachedir)` | `.ChdirF(traverse.UserCacheDir)` | `os.UserCacheDir()` |
| `$chdir($userconfigdir)` | `.ChdirF(traverse.UserConfigDir)` | `os.UserConfigDir()` |
| `$chdir($userhomedir)` | `.ChdirF(traverse.UserHomeDir)` | `os.UserHomeDir()` |
| `$chdir($xdgcachehome)` | `.ChdirF(traverse.XdgCacheHome)` | `$XDG_CACHE_HOME` or fallback to `UserCacheDir` |
| `$chdir($xdgconfighome)` | `.ChdirF(traverse.XdgConfigHome)` | `$XDG_CONFIG_HOME` or fallback to `UserConfigDir` |
| `$chdir($nixprofile)` | `.ChdirF(traverse.NixProfile)` | Nix profile directory |
### Flag Value References
In YAML specs, flag values are available as `${C_FLAG_<FLAGNAME>}` environment variables (uppercase, set via envsubst). In Go, use `traverse.Flag(cmd.Flag("flagname"))` to resolve the flag value at invoke time:
| YAML | Go |
|------|----|
| `$chdir(${C_FLAG_MYDIR})` | `.ChdirF(traverse.Flag(cmd.Flag("mydir")))` |
| `${C_FLAG_FORMAT}` in macro args | `cmd.Flag("format").Value.String()` in `ActionCallback` |
Prefer `ChdirF(traverse.Flag(...))` over `Chdir(flag.Value.String())` — it resolves the value lazily at invoke time.
### Generic vs Specific Modifier Application
In YAML, the `|||` delimiter controls modifier scope:
| YAML Syntax | Scope | Go Equivalent |
|-------------|-------|---------------|
| `["$files", "$chdir(/tmp)"]` | Generic — applies to **all** preceding actions | `carapace.ActionFiles().Chdir("/tmp")` |
| `["$files \|\|\| $chdir(/tmp)"]` | Specific — applies to **preceding value only** | `carapace.ActionFiles().Chdir("/tmp")` |
In Go, both translate to the same chained method calls since Go actions are composed by chaining.
### Static Values
Static completion values in specs translate to `ActionValues` or `ActionValuesDescribed`:
| YAML | Go |
|------|----|
| `["true", "false"]` | `carapace.ActionValues("true", "false")` |
| `["value\tdescription"]` | `carapace.ActionValuesDescribed("value", "description")` |
| `["value\tdesc\tblue"]` | `carapace.ActionStyledValuesDescribed("value", "desc", "blue")` |
### Subcommand Completions
For subcommands, create a separate `init()` function in the subcommand file:
```go
func init() {
carapace.Gen(subCmd).FlagCompletion(carapace.ActionMap{
"format": carapace.ActionValues("json", "yaml"),
})
carapace.Gen(subCmd).PositionalCompletion(
carapace.ActionDirectories(),
)
carapace.Gen(subCmd).PositionalAnyCompletion(
carapace.ActionFiles(),
)
}
```
## Complete Example
Given this YAML spec:
```yaml
name: traverse
flags:
--gitdir=: .git folder
--gitworktree=: root of the working directory for a non-bare repository
--parent=: first parent directory containing any of the given names/directories
--tempdir=: default directory to use for temporary files
--usercachedir=: root directory to use for user-specific cached data
--userconfigdir=: default root directory to use for user-specific configuration data
--userhomedir=: current user's home directory
--xdgcachehome=: cache directory (fallback to UserCacheDir)
--xdgconfighome=: home directory (fallback to UserConfigDir)
completion:
flag:
gitdir: ["$files", "$chdir($gitdir)"]
gitworktree: ["$files", "$chdir($gitworktree)"]
parent: ["$files", "$chdir($parent([go.mod, go.sum]))"]
tempdir: ["$files", "$chdir($tempdir)"]
usercachedir: ["$files", "$chdir($usercachedir)"]
userconfigdir: ["$files", "$chdir($userconfigdir)"]
userhomedir: ["$files", "$chdir($userhomedir)"]
xdgcachehome: ["$files", "$chdir($xdgcachehome)"]
xdgconfighome: ["$files", "$chdir($xdgconfighome)"]
```
The converted Go completer:
```go
package cmd
import (
"github.com/carapace-sh/carapace"
"github.com/carapace-sh/carapace/pkg/traverse"
"github.com/spf13/cobra"
)
var rootCmd = &cobra.Command{
Use: "traverse",
Short: "",
Run: func(cmd *cobra.Command, args []string) {},
}
func Execute() error {
return rootCmd.Execute()
}
func init() {
carapace.Gen(rootCmd).Standalone()
rootCmd.Flags().String("gitdir", "", ".git folder")
rootCmd.Flags().String("gitworktree", "", "root of the working directory for a non-bare repository")
rootCmd.Flags().String("parent", "", "first parent directory containing any of the given names/directories")
rootCmd.Flags().String("tempdir", "", "default directory to use for temporary files")
rootCmd.Flags().String("usercachedir", "", "root directory to use for user-specific cached data")
rootCmd.Flags().String("userconfigdir", "", "default root directory to use for user-specific configuration data")
rootCmd.Flags().String("userhomedir", "", "current user's home directory")
rootCmd.Flags().String("xdgcachehome", "", "cache directory (fallback to UserCacheDir)")
rootCmd.Flags().String("xdgconfighome", "", "home directory (fallback to UserConfigDir)")
carapace.Gen(rootCmd).FlagCompletion(carapace.ActionMap{
"gitdir": carapace.ActionFiles().ChdirF(traverse.GitDir),
"gitworktree": carapace.ActionFiles().ChdirF(traverse.GitWorkTree),
"parent": carapace.ActionFiles().ChdirF(traverse.Parent("go.mod", "go.sum")),
"tempdir": carapace.ActionFiles().ChdirF(traverse.TempDir),
"usercachedir": carapace.ActionFiles().ChdirF(traverse.UserCacheDir),
"userconfigdir": carapace.ActionFiles().ChdirF(traverse.UserConfigDir),
"userhomedir": carapace.ActionFiles().ChdirF(traverse.UserHomeDir),
"xdgcachehome": carapace.ActionFiles().ChdirF(traverse.XdgCacheHome),
"xdgconfighome": carapace.ActionFiles().ChdirF(traverse.XdgConfigHome),
})
}
```
## Relationship to Other Skills
| Skill | When to use instead of this skill |
|-------|----------------------------------|
| [references/spec.md](spec.md) | Writing YAML user specs — the *source* format for conversion |
| [references/macro.md](macro.md) | Looking up macro signatures and formatting macro arguments in YAML |
| [references/action.md](action.md) | Creating/modifying Go actions that become macros in the converted completer |
| [references/scrape.md](scrape.md) | Generating YAML specs from CLI source code — typically the step *before* conversion |
| [references/integrate.md](integrate.md) | Integrating carapace into an existing cobra app — use when the app already exists in Go |
| [references/mcp.md](mcp.md) | Using the `codegen` and `list_macros` MCP tools during conversion |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |