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/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 |
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