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/man.md
View on GitHub# Carapace Man Page Documentation
Reference for [carapace-man](https://github.com/carapace-sh/carapace-man) — providing inline documentation for completion values via YAML man pages.
## Overview
carapace-man provides contextual documentation for completion values. When a user selects a completion candidate, the UID of that action maps to a YAML file containing markdown descriptions. These descriptions are rendered inline (e.g. in the shell's completion menu) to help users understand what each completion value means.
Every UID is built the same way: `scheme://host/value`, where the value is the completion candidate itself. What differs is whether that value is a **known concept** or a **live entity**:
- `jj://revset-function/parents` — `parents` is a built-in function; its meaning is fixed and universal
- `jj://bookmark/main` — `main` is a bookmark; its meaning depends on which repo you're in
The YAML files are organized by scheme and host, and each value becomes a key in the YAML map. For known concepts, you can write all the keys upfront. For live entities, the keys are only known at runtime.
## Folder Structure
Man pages live in `~/.config/carapace/man/` (or `$XDG_CONFIG_HOME/carapace/man/`). The structure mirrors the UID scheme:
```
man/
├── cmd/ # Command specs (split YAML, see spec.md)
│ ├── git/
│ │ ├── git.yaml
│ │ ├── git.branch.yaml
│ │ └── git.log.yaml
│ └── ...
├── http/ # scheme = "http"
│ ├── method/
│ │ └── method.yaml
│ └── status/
│ └── status.yaml
├── jj/ # scheme = "jj"
│ ├── revset-function/
│ │ └── revset-function.yaml
│ ├── bookmark/
│ │ └── bookmark.yaml
│ └── ...
└── ps/ # scheme = "ps"
├── signal/
│ └── signal.yaml
└── state/
└── state.yaml
```
### cmd/ — Command Specs
The `cmd/` directory contains split YAML command specs (one file per subcommand). These are generated by `carapace-man split` from a full spec. See [spec.md](spec.md) for the YAML spec format.
### Non-cmd/ — Domain Documentation
All other top-level directories are **scheme** directories. Each scheme contains **host** subdirectories, and each host directory contains a single YAML file named `<host>.yaml`.
The UID `scheme://host/path` maps to:
- **File**: `man/<scheme>/<host>/<host>.yaml`
- **Key**: `path` (the path component of the UID, without leading `/`)
## YAML Format
Each YAML file is a map of **key → markdown description**:
```yaml
key1: |
Markdown description for key1.
Can span multiple lines and include `code`, **bold**, and [links](scheme://host/path).
key2: |
Markdown description for key2.
```
- Keys are the path component of the UID (e.g. for `jj://revset-function/parents`, the key is `parents`)
- Values are markdown strings rendered with [glamour](https://github.com/charmbracelet/glamour)
- Use the `|` YAML block scalar for multi-line descriptions
- Cross-references use UID-style links: `[text](scheme://host/path)`
### `./` Path Indirection
When a YAML value starts with `./`, it is treated as a relative path to another file whose content becomes the description. This is useful for large descriptions that don't fit inline:
```yaml
large_topic: ./detailed.md
```
The path is resolved relative to `man/<scheme>/<host>/`. The referenced file's entire content is returned as-is (not parsed as YAML).
## Known Concepts
Some UIDs refer to things whose meaning is fixed — a revset function, an HTTP method, a fileset operator. The documentation for these is the same everywhere and can be written once, covering every possible value.
### Examples
File: `man/jj/revset-function/revset-function.yaml`
```yaml
parents: |
`parents(x, [depth])`: `parents(x)` is the same as `x-`.
`parents(x, depth)` returns the parents of `x` at the given `depth`.
all: |
`all()`: All visible commits and ancestors of commits explicitly mentioned.
```
File: `man/jj/fileset-operator/fileset-operator.yaml`
```yaml
"&": |
`x & y`: Intersection — matches files in both `x` and `y`.
"|": |
`x | y`: Union — matches files in `x` or `y`.
"~": |
`x ~ y`: Difference — matches files in `x` but not in `y`.
```
File: `man/http/method/method.yaml`
```yaml
GET: |
The [GET](http://method/GET) HTTP method requests a representation of the specified resource.
POST: |
The [POST](http://method/POST) HTTP method sends data to the server.
```
## Live Entities
Other UIDs refer to things whose meaning depends on context — a bookmark name, a commit ID, a file path. The same key resolves to different content in different repos or on different machines:
- `jj://bookmark/main` → different commit in each repo
- `jj://commit/abc123` → different change depending on the repo
- `file:///etc/hosts` → different contents on each machine
The YAML file for a live-entity host contains a **conceptual entry** — a representative key that documents what kind of thing this category is. The actual per-value descriptions come from the live context at runtime.
### Example
File: `man/jj/bookmark/bookmark.yaml`
```yaml
local: |
A local bookmark in the jj repository. Bookmarks are jj's equivalent of Git branches.
Local bookmarks point to a single commit. Use `jj bookmark list` to see all local bookmarks.
```
The key `local` is a placeholder — at runtime the actual keys are the bookmark names from the current repository (`main`, `develop`, etc.). Since `Describe()` does an exact key lookup, a runtime value like `main` won't match `local`. The completion action's own `ActionValuesDescribed` descriptions (bookmark name → commit message) serve as the primary per-value documentation in this case.
### Populating Live-Entity Keys
To make `Describe()` resolve for live-entity UIDs, the YAML needs to contain the actual runtime values as keys. Approaches:
1. **Pre-populate common values** — add well-known entries (e.g. `main`, `trunk`) alongside the conceptual entry
2. **Sync from live context** — a generation step queries the system and writes actual keys with their current descriptions (e.g. `jj bookmark list` → populate `bookmark.yaml` with name→message entries)
The `./` path indirection can also point to a generated markdown file for a specific value.
## UID Resolution
The `Describe()` function resolves a UID to its description:
1. **`cmd://` scheme**: resolves the host (command name) against three sources in order: a user spec `~/.config/carapace/specs/<host>.yaml`, the compiled documentation database (bbolt), then the file `man/cmd/<host>/<host>.yaml`
2. **`man://` scheme**: Looks up a system man page by name and section
3. **Other schemes**: Loads `man/<scheme>/<host>/<host>.yaml` and looks up the key matching the UID's path
```go
// UID: jj://revset-function/parents
// File: man/jj/revset-function/revset-function.yaml
// Key: "parents" (UID.Path without leading "/")
```
## Adding Documentation for a New Scheme
1. Create the directory: `man/<scheme>/<host>/`
2. Create the YAML file: `man/<scheme>/<host>/<host>.yaml`
3. For **known concepts**: add entries for each possible value
4. For **live entities**: add a conceptual entry documenting the value type; optionally pre-populate common values or add a sync step
5. Set UIDs on the corresponding actions using `.Uid()` or `.UidF()`
## carapace-man CLI
The `carapace-man` tool provides subcommands:
| Command | Description |
|---------|-------------|
| `<uid>` | Print rendered documentation for a UID |
| `split <spec>` | Split a full YAML spec into per-subcommand files in `cmd/` |
| `split-to <spec> <output-dir>` | Split a spec into per-subcommand files in a specific output directory |
| `update <spec> <output-dir>` | Update `man/cmd/` docs from a fresh spec — runs spec-diff + split-to, preserving existing `documentation:` entries. Supports `--dry-run` |
| `spec-diff <spec> <existing-dir>` | Diff a fresh spec against existing cmd docs to detect drift |
| `man-to-md <command>` | Convert a system man page to markdown (`--section` for man page section). Falls back to `<command> --help` if no man page exists |
| `sync` | Clone/pull repo and sync `cmd/` docs. `--cmd-source` to sync from a local `man/cmd/` directory |
| `compile <spec> <output.db>` | Compile specs into a bbolt database (`--static`, `--man-dir` flags) |
| `inspect <db> [uid]` | Inspect contents of a compiled bbolt database (list UIDs or render one) |
### Update Workflow
For each completer:
1. **Update**: Run `carapace-man update` to refresh spec structure while preserving existing `documentation:` entries
```bash
carapace <completer> spec | carapace-man update - man/cmd/<completer>
carapace-man update --dry-run /tmp/<completer>-spec.yaml man/cmd/<completer>
```
2. **Audit**: Check the diff output from `update` (or run `spec-diff` separately) to see what needs docs
```bash
carapace <completer> spec > /tmp/<completer>-spec.yaml
carapace-man spec-diff /tmp/<completer>-spec.yaml man/cmd/<completer>
```
3. **Research**: For each subcommand needing `documentation.command`:
- Check the project's official documentation site first (most authoritative)
- Run `carapace-man man-to-md <command>` for system man pages
- If neither available, run `<command> --help`
- Stay close to official wording; rephrase only for consistency and length
4. **Write**: Fill in `documentation.command` and `documentation.flag` entries
5. **Validate**: Re-read edited files, verify no `[AI]` prefixes remain and run `carapace-man compile man carapace.db` (see [YAML Quoting](#yaml-quoting))
### YAML Quoting
`man/cmd/` is YAML data consumed by external tooling (carapace-man, editor language servers, downstream completion catalogs). These parsers stop at the first invalid file, so every file must stay valid YAML.
Flag descriptions are plain scalars: an unquoted `": "` is parsed as a new mapping key and invalidates the whole file. Quote such values (single quotes, doubled to escape a literal `'`):
```yaml
flags:
--dead-strip: 'Darwin: remove functions and data unreachable by entry point'
--seed=: 'Override the random seed (default: 0)'
```
Files written by `carapace-man update` are serialized with a YAML marshaller and are safe; manual edits must be validated by compiling the man pages:
```bash
carapace-man compile man carapace.db
```
### Research Source Material
Priority order for sourcing documentation:
1. **Official upstream docs** — the project's own documentation site (e.g. docs.docker.com, docs.brew.sh, cli.github.com/manual). Closest to authoritative; rephrase for consistency but stay faithful to the original meaning and technical accuracy.
2. **System man pages** — via `carapace-man man-to-md`. These are often derived from the upstream source and vetted by distributions.
3. **`<command> --help`** — last resort. Help output is often incomplete or auto-generated.
When rephrasing official docs:
- Preserve technical accuracy — enum values, default behaviors, and interaction effects must match the source
- Adjust tone and length to fit the skill's conventions (imperative mood, concise structure)
- Merge multiple paragraphs into a coherent summary where the full detail isn't needed
- Keep close to the original phrasing where it's already clear and concise — don't rewrite for the sake of rewriting
## Documentation Standards
### `documentation.command`
- First sentence: what the command does (imperative mood: "Create and start a new container")
- Remaining: key behavior, common usage patterns, important caveats
- Source from official upstream docs first, then man pages, then `--help`. Stay close to official wording for correctness; rephrase for consistency only
- Use UID cross-references where appropriate: `[git log](cmd://git/log)`, `[git-config](man://git-config/1)`
```yaml
documentation:
command: >-
Create and start a new container from an image. Configures the
container's filesystem, network, and resource constraints, then
executes the specified command. Use `docker create` to create a
container without starting it.
```
### `documentation.flag`
- Use the flag name without leading dashes as the key (e.g. `restart` not `--restart`)
- Include flag docs when upstream documentation is available — don't skip just because the short description seems clear enough, especially for complex CLIs
- Typical cases needing flag docs:
- Complex value types (enum values, patterns, formats)
- Non-obvious side effects or interactions with other flags
- Flags where short description is missing or terse
- Flags with subtle default behavior that differs from user expectation
- For simple CLIs, skip flag docs when the short description is already clear and sufficient
```yaml
flags:
--sig-proxy: Proxy received signals to the process
documentation:
flag:
sig-proxy: >
When set (default), signals received by `docker run` are forwarded
to the container process. Disable with `--sig-proxy=false` to
handle signals only on the client side.
```
### High-Quality Docs
These completers have high-quality documentation from official sources — use them as quality references:
- **git**: sourced from official Git man pages
- **jj**: auto-generated from Jujutsu CLI help output
- **but**: auto-generated from GitButler CLI help output
## Related Skills
- **references/action.md** — Action.Uid() and Action.UidF() modifiers
- **references/spec.md** — YAML command spec format (used by cmd/ entries)
- **references/mcp.md** — MCP server tools for man page access
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 |