name: update-completions description: > Keep shell completion scripts in sync with the CLI after adding a command, removing a command, adding/removing flags, or adding subcommands. Use after any change to index.ts subCommands, any command's args definition, or config/agent/tap subcommands. Invoke proactively — do not wait for the user to ask.

Update Completions

Run inline — do NOT spawn a subagent. You already know what changed; delegating forces a lossy re-briefing and creates gaps.

File Map

Sync Rules

1. index.ts is the source of truth. The subCommands object in index.ts is the authoritative command list. After any change, diff it against the commands= / commands=() / top-level -a lines in all three shell files.

2. Every command needs an entry in all three shells.

• bash: entry in the commands="..." string + a case block (even if just no-op or empty)
• zsh: entry in the commands=() array with description + optional case block under $words[1]
• fish: complete -c skilltap -n '__fish_use_subcommand' -a <cmd> -d '...' line

3. Flags must match the command's args definition. Read the command file (packages/cli/src/commands/<cmd>.ts) to get the definitive flag list. Boolean flags → --flag. String flags that take a value → annotate appropriately per shell.

4. Subcommands (tap, config, telemetry) need nested handling in each shell.

• bash: case "${COMP_WORDS[2]}" inside the parent command's block
• zsh: nested _arguments -C + case $state inside the parent command's block
• fish: __fish_seen_subcommand_from <parent>; and not __fish_seen_subcommand_from <subs> guard

5. Dynamic completions use --get-completions. Commands that complete against live data (skill names, tap names) call skilltap --get-completions <type> at completion time. Types defined in dynamic.ts:

• installed-skills — all installed skill names
• linked-skills — skills with scope: "linked" only
• tap-skills — skill names from all configured taps
• tap-names — tap names from config

6. Update tests. Three "script covers all top-level commands" tests in completions.test.ts enumerate every command. Add/remove entries there to match.

Shell Patterns

bash — adding a command

# 1. Add to commands string
local commands="... <newcmd>"

# 2. Add case block (flags only)
<newcmd>)
  COMPREPLY=($(compgen -W "--flag1 --flag2" -- "$cur"))
  ;;

# 3. If it takes a skill/tap name as positional:
<newcmd>)
  if [[ "$cur" == -* ]]; then
    COMPREPLY=($(compgen -W "--flag1" -- "$cur"))
  else
    local skills
    skills=$(skilltap --get-completions installed-skills 2>/dev/null)
    COMPREPLY=($(compgen -W "$skills" -- "$cur"))
  fi
  ;;

zsh — adding a command

# 1. Add to commands array
'<newcmd>:Short description'

# 2. Add case block
<newcmd>)
  _arguments \
    '--flag1[Description]' \
    '--flag2[Description]'
  ;;

# 3. If it takes a dynamic positional:
<newcmd>)
  local -a skills
  skills=(${(f)"$(skilltap --get-completions installed-skills 2>/dev/null)"})
  _arguments \
    '--flag1[Description]' \
    "1:skill:($skills)"
  ;;

fish — adding a command

# 1. Top-level entry
complete -c skilltap -n '__fish_use_subcommand' -a <newcmd> -d 'Short description'

# 2. Flag completions
complete -c skilltap -n '__fish_seen_subcommand_from <newcmd>' -l flag1 -d 'Description'

# 3. Dynamic positional
complete -c skilltap -n '__fish_seen_subcommand_from <newcmd>' -xa '(skilltap --get-completions installed-skills 2>/dev/null)'

Common Changes