Skip to main content
Alison Aquinas logoAlison's LLM Skills Marketplace

zoxide

Included in skill bundleshared-skillsView on GitHub ↗

Files

SKILL.mdagentsreferencesscripts

Install

Install only this skill with npx skills
npx skills add alisonaquinas/llm-shared-skills --skill 'zoxide' -g -y
Install the containing skill bundle
/plugin install shared-skills@llm-skills
Download zoxide-skill.zip
This skill is bundled inside shared-skills. Use npx skills when you only want this skill, or install the bundle once to make every included skill available through the plugin marketplace flow. Browse the full skill bundle repository at github.com/alisonaquinas/llm-shared-skills.

Invoke

Invoke this skill after installation
/shared-skills:zoxide

SKILL.md

name: zoxide description: > Efficient terminal directory navigation with zoxide (z, zi, and zoxide query). Use when users ask to jump to frequently used directories, select directories by keywords, set up or troubleshoot zoxide shell integration, resolve ranked directory matches for scripts, migrate from z/autojump/fasd, configure fzf interactive mode, or investigate database location.

Zoxide Navigation

Use zoxide-first navigation when the target directory is implied by keywords or history instead of a fixed absolute path.

Prerequisite Check

Run this before proposing z, zi, or query-based navigation:

command -v zoxide >/dev/null 2>&1 || zoxide --version

If zoxide is missing, surface that first and either run scripts/install.sh or scripts/install.ps1, or fall back to ordinary cd, find, and explicit absolute paths.

Intent Router

RequestReferenceLoad When
Install tool, first-time setupreferences/install-and-setup.mdUser needs to install zoxide or fzf, or do initial shell setup
Shell setup, fzf config, migrationreferences/zoxide-setup-and-config.mdUser needs init commands, database location, or fzf setup
Preflight and environmentscripts/probe-zoxide.shVerify shell integration and check database status

Quick Start

# Initialize in shell startup file (~/.bashrc, ~/.zshrc, etc.)
eval "$(zoxide init bash)"

# Or for zsh:
eval "$(zoxide init zsh)"
  1. Confirm the binary: zoxide --version
  2. Confirm shell integration: type z and type zi
  3. Use zoxide query <keywords> before destructive work
  4. If zoxide is unavailable, use explicit cd <path> or find instead of implied matches

Workflow

  1. Confirm intent:
  • Exact path available -> use cd <path>.
  • Best historical match by keywords -> use z <keywords>.
  • User wants to choose among matches -> use zi <keywords> or zoxide query -i <keywords>.
  • Script needs path without changing directory -> use zoxide query <keywords>.
  1. Confirm setup when needed:
  • command -v zoxide
  • type z
  • type zi
  1. Run the mapped command:
  • Jump to best match: z <keywords>
  • Interactive picker: zi <keywords>
  • Return best match path: zoxide query <keywords>
  • List matches: zoxide query -l <keywords>
  • List matches with score: zoxide query -ls <keywords>
  • Add path explicitly: zoxide add <path>
  • Remove stale path: zoxide remove <path>
  1. Validate destination before risky operations:
  • Print pwd after jump, or inspect with zoxide query -l <keywords> first.

Safety and Guardrails

OperationGuardrailWhy
Interactive jumpUse zi or verify with zoxide query -l firstMultiple matches may not be what expected
Destructive opsValidate target with pwd after jumpVerify correct directory before rm/move
ScriptsUse zoxide query not zz depends on shell integration; not reliable in subshells
High-impactResolve and inspect with zoxide query -l <keywords> before proceedingConfirm directory explicitly

Automation Guardrails

  • Prefer deterministic path resolution in scripts:
target="$(zoxide query <keywords>)"
cd "$target"
  • Use zoxide query in automation instead of z, because z depends on shell integration and interactive session state.
  • For destructive or high-impact work, resolve with query -l and verify the chosen directory explicitly.
  • Run probe script first: scripts/probe-zoxide.sh to verify shell integration and database status
  • Recovery note: when zoxide is unavailable, switch to explicit paths. The fallback is safer than simulating history-based ranking with guesswork.

Troubleshooting

  • z or zi missing: initialize shell integration with zoxide init <shell> and load it from shell startup files.
  • Wrong match chosen: add more keywords or inspect ranked results with zoxide query -ls <keywords>.
  • Stale entries: run zoxide remove <path> or zoxide edit.
  • No results: navigate manually once, then run zoxide add <path> if needed.

Environment Knobs

  • _ZO_ECHO=1: print matched path before changing directory.
  • _ZO_EXCLUDE_DIRS: exclude glob patterns from ranking.
  • _ZO_MAXAGE: tune aging and cleanup aggressiveness.
  • _ZO_FZF_OPTS: customize interactive picker behavior.
← Back to marketplace