Agent skill

asdf

Use this skill whenever the user wants to install, configure, or use asdf (asdf-vm), the universal version manager. Trigger for any mention of asdf, .tool-versions files, managing runtime versions, switching between versions of Node.js, Python, Ruby, Go, Terraform, kubectl, Java, Erlang, Elixir, or any other tool managed by asdf. Also trigger when migrating from nvm, pyenv, rbenv, goenv, tfenv, or similar single-language version managers. Use this skill for help with asdf plugins, asdf install, asdf set/global/local, troubleshooting shims, Fish/Bash/Zsh shell configuration, and multi-project version isolation workflows.

View SKILL.md on GitHub Repository
Stars 100
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/jjmartres/opencode/tree/main/opencode/skill/asdf

SKILL.md

asdf Version Manager Skill

asdf is a universal CLI version manager — one tool to replace nvm, pyenv, rbenv, tfenv, goenv and more. It manages per-project versions via .tool-versions files and switches versions automatically as you navigate directories.

When to Use This Skill

Use this skill when the user is:

  • Installing or setting up asdf on a new machine (any OS, any shell)
  • Adding plugins for a language or tool (Node.js, Python, Go, Terraform, kubectl, Helm, etc.)
  • Installing or switching versions of any tool managed by asdf
  • Managing .tool-versions files — creating, editing, or understanding version resolution
  • Migrating from single-language version managers like nvm, pyenv, rbenv, goenv, tfenv, or sdkman
  • Configuring shell integration for Bash, Zsh, Fish, or Elvish
  • Debugging version resolution — wrong version active, shims not working, command not found errors
  • Onboarding to a project that uses .tool-versions for reproducible environments
  • Setting up CI/CD pipelines that need deterministic tool versions via asdf
  • Configuring .asdfrc for legacy file support, concurrency, or plugin repository settings

Core Concepts

  • Plugin: Adapter for a specific tool (nodejs, python, terraform, kubectl, etc.)
  • Tool: The actual runtime/binary managed (e.g., Node.js 20.11.0)
  • .tool-versions: Project-level file declaring exact versions; asdf resolves it by traversing up the directory tree to $HOME
  • Shims: Lightweight wrappers in ~/.asdf/shims/ that intercept tool invocations and dispatch to the right version
  • Version scopes: project (.tool-versions in cwd) → parent dirs → $HOME/.tool-versions → env var ASDF_${TOOL}_VERSION

Installation

Dependencies (all platforms)

bash
# Debian/Ubuntu
sudo apt install -y git curl

# macOS
brew install git curl

Install asdf binary (recommended: binary download)

bash
# Download latest release from https://github.com/asdf-vm/asdf/releases
# Or via git clone (classic method):
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.16.7

Shell Configuration

Fish shell (Jean-Jacques' setup):

fish
# Add to ~/.config/fish/config.fish
source ~/.asdf/asdf.fish

# Install completions
mkdir -p ~/.config/fish/completions
ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions/asdf.fish

Bash:

bash
# Add to ~/.bashrc or ~/.bash_profile
. "$HOME/.asdf/asdf.sh"
. "$HOME/.asdf/completions/asdf.bash"

Zsh:

zsh
# Add to ~/.zshrc
. "$HOME/.asdf/asdf.sh"

After configuration, restart shell or source the config file.

Essential Commands

Plugin Management

bash
asdf plugin list all              # Browse all available plugins
asdf plugin list all | grep terra # Search for specific plugins
asdf plugin add nodejs            # Add plugin by shortname (from registry)
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git  # Add by URL
asdf plugin list                  # List installed plugins
asdf plugin update nodejs         # Update a plugin
asdf plugin update --all          # Update all plugins
asdf plugin remove nodejs         # Remove plugin + all its installs

Version Management

bash
asdf list all nodejs              # List all installable versions
asdf list all nodejs 20           # List versions matching prefix
asdf install nodejs latest        # Install latest version
asdf install nodejs 20.11.0       # Install specific version
asdf install                      # Install all versions in .tool-versions
asdf list nodejs                  # List installed versions
asdf uninstall nodejs 18.0.0      # Remove a version

Setting Versions

bash
asdf set nodejs 20.11.0           # Set version in ./.tool-versions (project)
asdf set -u nodejs 20.11.0        # Set version in ~/.tool-versions (global/user default)
asdf set -p nodejs 20.11.0        # Set in nearest parent .tool-versions
asdf set nodejs latest            # Resolve and write latest version
asdf current                      # Show active version for all tools in cwd
asdf current nodejs               # Show active version for one tool
asdf where nodejs                 # Show install path for active version
asdf which node                   # Show shim path for a command

Note: asdf set replaced the older asdf local / asdf global commands in asdf v0.15+. Both still work but asdf set is the modern API.

Environment Variable Override

bash
# Temporarily override without editing .tool-versions
ASDF_NODEJS_VERSION=18.0.0 node --version

.tool-versions Format

nodejs 20.11.0
python 3.12.2
terraform 1.7.4
kubectl 1.29.2
golang 1.22.1
  • One tool per line, <name> <version>
  • Multiple versions separated by spaces (fallback chain): python 3.12.2 2.7.18
  • Special keywords: system (use OS-installed version), path:~/my/custom/build
  • Commit to version control — this is the contract for the project's tool versions

.asdfrc Configuration

Located at ~/.asdfrc:

ini
# Support .nvmrc, .ruby-version, etc. (per-plugin support required)
legacy_version_file = yes

# Keep downloaded archives (useful for slow connections)
always_keep_download = no

# Concurrency for parallel installs
concurrency = auto

# Plugin repository refresh interval in minutes
plugin_repository_last_check_duration = 60

Common Plugins for DevOps/Cloud (Jean-Jacques' stack)

Tool Plugin add command
Node.js asdf plugin add nodejs
Python asdf plugin add python
Go asdf plugin add golang
Terraform asdf plugin add terraform
kubectl asdf plugin add kubectl
Helm asdf plugin add helm
gcloud CLI asdf plugin add gcloud
Skaffold asdf plugin add skaffold
Java asdf plugin add java
Ruby asdf plugin add ruby
Erlang asdf plugin add erlang
Elixir asdf plugin add elixir

Many plugins may require system dependencies — always check the plugin's README before installing.

Migration from Other Version Managers

Enable legacy file support in ~/.asdfrc:

ini
legacy_version_file = yes
Old file Tool
.nvmrc nodejs (via asdf-nodejs)
.node-version nodejs
.ruby-version ruby (via asdf-ruby)
.python-version python (via asdf-python)

Troubleshooting

Shims not working / command not found

bash
asdf reshim nodejs          # Regenerate shims for a plugin
asdf reshim                 # Regenerate all shims
echo $PATH                  # Verify ~/.asdf/shims is early in PATH
type -a node                # Fish: check which binary is resolved

Version not being picked up

bash
asdf current                # See what version is resolved and from where
# Look for "No version set" warnings
# Check .tool-versions exists in project dir or a parent

Plugin install failures

  • Check plugin README for system dependency requirements
  • Ensure git is installed and accessible
  • For nodejs: may need gnupg for keyring verification

Data directory

Default: ~/.asdf/ — override with export ASDF_DATA_DIR=/custom/path in shell config.

Typical Project Onboarding Workflow

bash
# 1. Clone project
git clone <repo> && cd <repo>

# 2. Add plugins for each tool in .tool-versions (if not already added)
asdf plugin add nodejs
asdf plugin add python

# 3. Install all versions specified in .tool-versions
asdf install

# 4. Verify
asdf current

Reference

Recommended Agent Skills

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

jjmartres/opencode

file-organizer

Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.

100 8
Explore
jjmartres/opencode

Work on Ticket

Fetches Jira ticket details, creates an appropriately named branch, and initiates the task planning workflow. Use when the user says "work on [TICKET_ID]" or similar phrases.

100 8
Explore
jjmartres/opencode

meeting-insights-analyzer

Analyzes meeting transcripts and recordings to uncover behavioral patterns, communication insights, and actionable feedback. Identifies when you avoid conflict, use filler words, dominate conversations, or miss opportunities to listen. Perfect for professionals seeking to improve their communication and leadership skills.

100 8
Explore
jjmartres/opencode

skill-judge

Evaluate Agent Skill design quality against official specifications and best practices. Use when reviewing, auditing, or improving SKILL.md files and skill packages. Provides multi-dimensional scoring and actionable improvement suggestions.

100 8
Explore
jjmartres/opencode

MCP Builder Skill

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

100 8
Explore
jjmartres/opencode

notion

Manage Notion pages and databases from the CLI using notion-cli. Create, read, search, and update pages. Query databases, add entries, and manage blocks and properties.

100 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results