---
name: shell-completion
description: Install and configure shell auto-completion for common CLI tools on macOS (zsh/bash)
license: MIT
compatibility: opencode
metadata:
  platform: macos
  shells: zsh,bash
---

## What I do

Guide the installation and configuration of shell command-line auto-completion on macOS.
Covers both zsh (default macOS shell) and bash.

## When to use me

Use this skill when the user wants to:
- Enable tab completion for CLI tools (git, npm, docker, kubectl, etc.)
- Fix missing or broken shell completions
- Set up completion on a new macOS machine
- Add completions to their existing shell configuration

## Workflow

### Step 1: Detect the shell environment

Ask the user which shell they use, or detect it with:

```bash
echo $SHELL
```

### Step 2: Check existing completion setup

```bash
# Check if completion frameworks are installed
brew list bash-completion 2>/dev/null && echo "bash-completion installed" || echo "bash-completion not installed"
brew list zsh-completions 2>/dev/null && echo "zsh-completions installed" || echo "zsh-completions not installed"

# Check current completion config in shell rc file
grep -n "completion" ~/.zshrc ~/.bash_profile ~/.bashrc 2>/dev/null
```

### Step 3: Install completion frameworks

For zsh users:
```bash
# Install zsh-completions via Homebrew
brew install zsh-completions

# Add to ~/.zshrc if not present
cat >> ~/.zshrc << 'EOF'
# zsh-completions
if type brew &>/dev/null; then
  FPATH="$(brew --prefix)/share/zsh-completions:$FPATH"
  autoload -Uz compinit
  compinit
fi
EOF
```

For bash users:
```bash
# Install bash-completion via Homebrew
brew install bash-completion

# Add to ~/.bash_profile or ~/.bashrc
cat >> ~/.bash_profile << 'EOF'
# bash-completion
if [ -f "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]; then
  . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
fi
EOF
```

### Step 4: Install completions for common tools

For each tool the user has installed, add its completion:

**git**
```bash
# zsh: usually included with git, zsh-completions handles it
# bash: ensure bash-completion is sourced
```

**npm / npx**
```bash
npm completion >> ~/.zshrc   # for zsh
npm completion >> ~/.bashrc  # for bash
```

**docker**
```bash
# Docker Desktop for Mac usually installs completions automatically
# Verify symlinks exist:
ls -la /Applications/Docker.app/Contents/Resources/etc/
```

**kubectl**
```bash
kubectl completion zsh > ~/.zshrc.d/kubectl
kubectl completion bash > ~/.bashrc.d/kubectl
```

**brew**
```bash
# zsh: handled by zsh-completions
# bash: source bash-completion first
```

### Step 5: Create a completions directory (recommended)

```bash
# Create a dedicated completions directory
mkdir -p ~/.config/completions

# Add to shell rc:
# For zsh in ~/.zshrc:
#   fpath=(~/.config/completions $fpath)
# For bash in ~/.bashrc:
#   for f in ~/.config/completions/*; do source "$f"; done
```

### Step 6: Reload shell and verify

```bash
source ~/.zshrc   # or ~/.bashrc / ~/.bash_profile
# Test completion by typing a command and pressing Tab
git --<TAB>
```

## Common troubleshooting

| Issue | Solution |
|-------|----------|
| `compinit: function definition file not found` | Run `rm -f ~/.zcompdump; compinit` |
| Completions not loading | Check `FPATH` order: `brew --prefix` should come first |
| Slow shell startup | Add `skip_global_compinit=1` before `compinit` |
| Permission denied errors | Run `chmod go-w /usr/local/share` |
| bash completions not working | Make sure `bash-completion@2` is installed (for bash 4+) |

## Key notes for the agent

- macOS Ventura+ uses zsh as the default shell. Do NOT change the user's default shell unless explicitly requested.
- Always append to shell config files, never overwrite them.
- Before modifying, always back up: `cp ~/.zshrc ~/.zshrc.bak.$(date +%s)`
- If brew is not installed, guide the user to install it first: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
- Some completions (like for npx) are slow; consider adding cache mechanisms if the user complains about slow startup.