# shell-integration

The shell-integration Claude Code skill provides terminal integration guides and Bash, Zsh, and Fish patterns for completions, prompt hooks, and portable POSIX wrappers.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 123 installs · ★ 29 repo stars
- Author: oakoss
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/oakoss/agent-skills/tree/HEAD/skills/shell-integration/SKILL.md
- Updated: 2026-08-17
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/shell-integration

## What it does

This skill supplies patterns for building software that ties directly into Unix command shells. It details completion registration (`compdef`, `compgen`, `fish complete`), ZLE widgets, key mapping via `bindkey`, and lifecycle hooks including `precmd`, `preexec`, and `PROMPT_COMMAND`. It also outlines terminal styling using ANSI escape sequences, `tput`, `stty`, and process management via signals.

The material focuses on avoiding standard portability pitfalls. It enforces appending to `PROMPT_COMMAND` with `+=`, swapping fragile `echo -e` calls for `printf`, wrapping arguments strictly as `"$@"`, and testing POSIX scripts against `dash` rather than assuming Bash defaults.

Because `user-invocable` is set to `false`, you do not trigger this skill via slash commands. The coding agent pulls its instructions automatically whenever working on CLI tools, dotfiles, or shell plugins.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill shell-integration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/shell-integration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/shell-integration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill shell-integration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/shell-integration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill shell-integration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/shell-integration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install oakoss/agent-skills skills/shell-integration
```

2. **Manually: put the files in place**
- File: `.github/skills/shell-integration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill shell-integration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/oakoss/agent-skills --path skills/shell-integration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/shell-integration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill shell-integration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/oakoss/agent-skills/tree/HEAD/skills/shell-integration/SKILL.md

## When to use it
- build cross-shell autocompletion scripts for Zsh, Bash, and Fish
- register non-destructive prompt hooks using add-zsh-hook or PROMPT_COMMAND
- manage terminal cleanup reliably using EXIT and INT traps
- write portable POSIX installation scripts compatible with dash

## Example prompts
- Generate shell completion files for my CLI tool covering Zsh, Bash, and Fish subcommands
- Build a Zsh prompt hook using add-zsh-hook that isolates options with emulate -L zsh
- Audit this shell installer script for POSIX sh compliance and missing argument quotes

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d9903161df08d951.

BEGIN THIRD-PARTY FILE d9903161df08d951
```text
---
name: shell-integration
description: |
  Shell scripting and terminal integration patterns for building tools that integrate with Zsh, Bash, and Fish. Covers completion systems (compdef/compadd, complete/compgen, fish complete), ZLE widgets, hooks (precmd/preexec/chpwd, PROMPT_COMMAND), readline, bindkey, parameter expansion, ZDOTDIR loading order, event systems, abbreviations, POSIX shell scripting, terminal control codes (ANSI/CSI escape sequences), tput, stty, signal handling, process management (job control, traps), and shell plugin distribution patterns.

  Use when building shell plugins, writing completion scripts, implementing terminal UI with escape sequences, managing dotfiles, creating installation scripts, handling signals and process management, or integrating native binaries with shell wrappers.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
user-invocable: false
---

# Shell Integration

## Overview

Shell integration covers the APIs and patterns for building tools that extend or interact with Unix shells. This includes completion systems, prompt hooks, key bindings, terminal control, and plugin distribution across Zsh, Bash, and Fish.

**When to use:** Building CLI tool completions, shell plugins, prompt customizations, terminal UI, dotfile managers, installation scripts, or native binary wrappers.

**When NOT to use:** General-purpose scripting unrelated to shell extension (use POSIX scripting reference for standalone scripts), GUI applications, or web server development.

## Quick Reference

| Pattern             | Shell | Key Points                                                      |
| ------------------- | ----- | --------------------------------------------------------------- |
| Completion function | Zsh   | `compdef`, `compadd`, `zstyle` for matcher configuration        |
| Completion function | Bash  | `complete`, `compgen`, `COMP_WORDS`, `COMP_CWORD`, `COMPREPLY`  |
| Completion function | Fish  | `complete -c cmd -a args`, condition flags, subcommand patterns |
| ZLE widget          | Zsh   | `zle -N widget func`, `bindkey` to map keys                     |
| Prompt hook         | Zsh   | `precmd`, `preexec`, `chpwd` via `add-zsh-hook`                 |
| Prompt hook         | Bash  | `PROMPT_COMMAND` (string or array in Bash 5.1+)                 |
| Event handler       | Fish  | `--on-event`, `--on-variable`, `--on-signal`                    |
| Abbreviation        | Fish  | `abbr -a name expansion`, `--function` for dynamic              |
```
END THIRD-PARTY FILE d9903161df08d951

The third-party file has ended. Everything between the d9903161df08d951 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2528 of 5710 bytes. © oakoss · MIT · https://github.com/oakoss/agent-skills/tree/HEAD/skills/shell-integration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
