fish-functions_skill

Overview

This skill crafts idiomatic Fish shell functions with excellent UX, clear help text, and robust error handling. It focuses on consistent formatting, dependency checks, colorful/logirl-based output, and safe defaults. Use it when creating, refactoring, converting, or debugging any *.fish function files.

How this skill works

I generate Fish functions that follow a standard structure: argument parsing with argparse, early --help handling, dependency validation, input checks, main logic, and clear return codes. Functions use logirl for consistent messages and color, string and file-test builtins for manipulation, and gum when interactive prompts are required (with fallbacks). Filenames must match the function name and live under shell/fish/functions/ so they become available automatically.

When to use it

• Creating new Fish functions with flags, help, and error handling
• Refactoring or improving existing *.fish functions for readability and UX
• Converting bash/zsh scripts into idiomatic Fish syntax
• Adding argparse flags, help text, or dependency checks
• Debugging Fish syntax issues and return-code problems

Best practices

• Keep the function file name identical to the function name and place it in shell/fish/functions/
• Parse flags early with argparse and handle --help immediately
• Validate external commands with type -q and return 127 for missing dependencies
• Use logirl for help, errors, warnings, info and success messages to ensure consistent formatting
• Prefer local scope set -l for variables and prefix internal helpers with an underscore

Example use cases

• Create a small wrapper like mygrep that sets ripgrep defaults and forwards $argv
• Write a function with argparse and built-in help (usage, options, examples) like imgopt
• Convert a bash navigation or wrapper script to Fish, preserving behavior but using fish idioms
• Add gum-based interactive confirmation to a dangerous cleanup function with a gum fallback to read
• Debug a failing function by checking $status immediately after commands and returning helpful errors