Agent skill

shell-completion-generator

Generate shell completion scripts for bash, zsh, and fish from CLI command definitions. Creates intelligent completions with argument suggestions, file completions, and dynamic values.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/cli-mcp-development/skills/shell-completion-generator

SKILL.md

Shell Completion Generator

Generate comprehensive shell completion scripts for bash, zsh, and fish shells from CLI command definitions.

Capabilities

  • Generate bash completion scripts
  • Generate zsh completion with descriptions
  • Generate fish completion scripts
  • Support for subcommands and nested commands
  • Dynamic completion for arguments
  • File/directory path completion
  • Custom completion functions

Usage

Invoke this skill when you need to:

  • Add shell completions to a CLI application
  • Generate completions from command schemas
  • Create custom completion logic
  • Support multiple shells

Inputs

Parameter Type Required Description
cliName string Yes Name of the CLI executable
commands array Yes Command definitions with options
shells array No Target shells (default: all)
outputDir string No Output directory for scripts
dynamic object No Dynamic completion configurations

Command Definition Structure

json
{
  "commands": [
    {
      "name": "deploy",
      "description": "Deploy application to environment",
      "options": [
        {
          "flags": ["-e", "--env"],
          "description": "Target environment",
          "type": "choice",
          "choices": ["dev", "staging", "prod"]
        },
        {
          "flags": ["-c", "--config"],
          "description": "Config file path",
          "type": "file",
          "extensions": [".json", ".yaml", ".yml"]
        }
      ],
      "arguments": [
        {
          "name": "service",
          "description": "Service to deploy",
          "type": "dynamic",
          "source": "services-list"
        }
      ],
      "subcommands": [
        {
          "name": "status",
          "description": "Check deployment status"
        }
      ]
    }
  ]
}

Output Structure

completions/
├── bash/
│   └── <cliName>.bash       # Bash completion script
├── zsh/
│   └── _<cliName>           # Zsh completion function
├── fish/
│   └── <cliName>.fish       # Fish completion script
└── install.sh               # Installation helper script

Generated Code Patterns

Bash Completion Script

bash
#!/bin/bash
# Completion script for mycli

_mycli_completions() {
    local cur prev words cword
    _init_completion || return

    local commands="deploy rollback status config"

    case "${prev}" in
        mycli)
            COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
            return
            ;;
        deploy)
            COMPREPLY=($(compgen -W "--env --config --dry-run" -- "${cur}"))
            return
            ;;
        --env|-e)
            COMPREPLY=($(compgen -W "dev staging prod" -- "${cur}"))
            return
            ;;
        --config|-c)
            _filedir '@(json|yaml|yml)'
            return
            ;;
    esac

    # Handle subcommands
    if [[ ${words[1]} == "deploy" ]]; then
        case "${prev}" in
            status)
                # Dynamic completion for services
                local services=$(_mycli_get_services)
                COMPREPLY=($(compgen -W "${services}" -- "${cur}"))
                return
                ;;
        esac
    fi

    COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
}

# Dynamic completion helper
_mycli_get_services() {
    mycli services list --quiet 2>/dev/null
}

complete -F _mycli_completions mycli

Zsh Completion Script

zsh
#compdef mycli

_mycli() {
    local -a commands
    commands=(
        'deploy:Deploy application to environment'
        'rollback:Rollback to previous version'
        'status:Check deployment status'
        'config:Manage configuration'
    )

    local -a deploy_options
    deploy_options=(
        '(-e --env)'{-e,--env}'[Target environment]:environment:(dev staging prod)'
        '(-c --config)'{-c,--config}'[Config file path]:config file:_files -g "*.{json,yaml,yml}"'
        '--dry-run[Preview changes without applying]'
    )

    _arguments -C \
        '1: :->command' \
        '*:: :->args'

    case $state in
        command)
            _describe -t commands 'mycli commands' commands
            ;;
        args)
            case $words[1] in
                deploy)
                    _arguments $deploy_options \
                        '1:service:_mycli_services'
                    ;;
                rollback)
                    _arguments \
                        '(-v --version)'{-v,--version}'[Version to rollback]:version:_mycli_versions'
                    ;;
            esac
            ;;
    esac
}

# Dynamic completion for services
_mycli_services() {
    local -a services
    services=(${(f)"$(mycli services list --quiet 2>/dev/null)"})
    _describe -t services 'services' services
}

_mycli "$@"

Fish Completion Script

fish
# Completions for mycli

# Disable file completions by default
complete -c mycli -f

# Main commands
complete -c mycli -n __fish_use_subcommand -a deploy -d 'Deploy application to environment'
complete -c mycli -n __fish_use_subcommand -a rollback -d 'Rollback to previous version'
complete -c mycli -n __fish_use_subcommand -a status -d 'Check deployment status'
complete -c mycli -n __fish_use_subcommand -a config -d 'Manage configuration'

# Deploy options
complete -c mycli -n '__fish_seen_subcommand_from deploy' -s e -l env -d 'Target environment' -xa 'dev staging prod'
complete -c mycli -n '__fish_seen_subcommand_from deploy' -s c -l config -d 'Config file path' -r -F
complete -c mycli -n '__fish_seen_subcommand_from deploy' -l dry-run -d 'Preview changes'

# Deploy subcommands
complete -c mycli -n '__fish_seen_subcommand_from deploy' -a status -d 'Check deployment status'

# Dynamic service completion
function __mycli_services
    mycli services list --quiet 2>/dev/null
end

complete -c mycli -n '__fish_seen_subcommand_from deploy; and not __fish_seen_subcommand_from status' -a '(__mycli_services)' -d 'Service'

Completion Types

Type Description Example
choice Fixed list of values environments, formats
file File path completion config files
directory Directory path completion output paths
dynamic Runtime-generated values services, branches
command Subcommand completion nested commands
none No completion free-form text

Dynamic Completion Sources

json
{
  "dynamic": {
    "services-list": {
      "command": "mycli services list --quiet",
      "cache": 60
    },
    "git-branches": {
      "command": "git branch --format='%(refname:short)'",
      "cache": 10
    },
    "docker-images": {
      "command": "docker images --format '{{.Repository}}:{{.Tag}}'",
      "cache": 30
    }
  }
}

Installation Script

bash
#!/bin/bash
# install.sh - Install shell completions for mycli

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

install_bash() {
    local dest="${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/bash/mycli.bash" "$dest/mycli"
    echo "Installed bash completion to $dest/mycli"
}

install_zsh() {
    local dest="${ZDOTDIR:-$HOME}/.zfunc"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/zsh/_mycli" "$dest/_mycli"
    echo "Add 'fpath=(~/.zfunc \$fpath)' to .zshrc if not present"
    echo "Installed zsh completion to $dest/_mycli"
}

install_fish() {
    local dest="${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/fish/mycli.fish" "$dest/mycli.fish"
    echo "Installed fish completion to $dest/mycli.fish"
}

case "$1" in
    bash) install_bash ;;
    zsh) install_zsh ;;
    fish) install_fish ;;
    all|"")
        install_bash
        install_zsh
        install_fish
        ;;
    *)
        echo "Usage: $0 [bash|zsh|fish|all]"
        exit 1
        ;;
esac

Workflow

  1. Parse command definitions - Extract commands, options, arguments
  2. Identify completion types - Map types to shell completion methods
  3. Generate bash script - Create complete-function based script
  4. Generate zsh script - Create _compdef function with descriptions
  5. Generate fish script - Create complete commands
  6. Create install script - Helper for users to install

Best Practices Applied

  • Descriptions in zsh completions
  • File extension filtering
  • Caching for dynamic completions
  • Subcommand handling
  • Option grouping (-e|--env)
  • Context-aware completions

References

Target Processes

  • shell-completion-scripts
  • cli-documentation-generation
  • cli-application-bootstrap

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results