skills/skills/update-opencode/README.md

Update OpenCode Skill

Automate checking for and applying OpenCode version updates in Nix-based dotfiles.

Features

• Check versions: Compare current OpenCode installation against latest GitHub release
• Auto-update: Fetch SHA256 hashes and update Nix package definitions
• Verify installations: Confirm successful updates after rebuild
• Version pinning: Install specific versions for compatibility

Installation

Global Installation (Recommended)

1. Copy this skill to your dotfiles:

cd ~/proj/skills
./bin/deploy-skill.sh update-opencode

2. Follow displayed instructions to update modules/ai-skills.nix in your dotfiles

3. Rebuild system:

cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#<hostname>

4. Verify installation:

ls ~/.claude/skills/update-opencode
ls ~/.config/opencode/skills/update-opencode

Project-Local Installation (Alternative)

For use in a specific project only:

mkdir -p .claude/skills .opencode/skills
cp -r ~/proj/skills/skills/update-opencode .claude/skills/
cp -r ~/proj/skills/skills/update-opencode .opencode/skills/

Prerequisites

Required tools:

• jq - JSON parsing
• curl - HTTP requests
• nix-prefetch-url - Binary hash computation
• sed - File editing
• grep - Pattern matching

Required access:

• Read/write to dotfiles repository (~/proj/dotfiles by default)
• sudo permissions for nixos-rebuild switch
• Network access to GitHub API

Verify prerequisites:

command -v jq curl nix-prefetch-url sed grep && echo "✓ All tools available"

Usage

With AI Agents (Claude Code / OpenCode)

Simply ask the agent:

• "Check for OpenCode updates"
• "Update OpenCode to latest"
• "Install OpenCode version 1.0.44"

The agent will use this skill automatically.

Manual Usage

Check current vs latest version:

~/.claude/skills/update-opencode/scripts/check-version.sh

Fetch SHA256 for specific version:

~/.claude/skills/update-opencode/scripts/fetch-sha256.sh 1.0.51

Update Nix file (dry-run first):

~/.claude/skills/update-opencode/scripts/update-nix-file.sh 1.0.51 sha256-ABC... --dry-run
~/.claude/skills/update-opencode/scripts/update-nix-file.sh 1.0.51 sha256-ABC...

Rebuild system:

cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#<hostname>

Verify installation:

~/.claude/skills/update-opencode/scripts/verify-update.sh 1.0.51

Configuration

Custom dotfiles path:

# Set via environment variable
export DOTFILES_PATH=~/my-dotfiles

# Or pass as argument
./check-version.sh --dotfiles ~/my-dotfiles
./update-nix-file.sh 1.0.51 sha256-ABC... --dotfiles ~/my-dotfiles

Troubleshooting

"Error: Nix file not found"

• Verify dotfiles path is correct
• Check that pkgs/opencode/default.nix exists

"Error: Failed to query GitHub API"

• Check network connectivity
• Verify GitHub API is reachable: curl -s https://api.github.com/repos/sst/opencode/releases/latest
• Check for rate limiting (60 requests/hour unauthenticated)

"Error: Failed to fetch or hash"

• Verify version exists on GitHub releases
• Check network connectivity to GitHub
• Ensure nix-prefetch-url is installed

"Verification failed: Version mismatch"

• Rebuild may not have completed successfully
• Check rebuild logs for errors
• Try re-running: cd ~/proj/dotfiles && sudo nixos-rebuild switch --flake .#<hostname>

"Error: Required command not found"

• Install missing tools via Nix or system package manager
• For NixOS, add to environment.systemPackages in configuration

Files

skills/update-opencode/
├── SKILL.md                          # Agent instructions
├── README.md                         # This file
├── scripts/
│   ├── check-version.sh              # Compare versions
│   ├── fetch-sha256.sh               # Fetch SRI hash
│   ├── update-nix-file.sh            # Modify Nix file
│   └── verify-update.sh              # Verify installation
├── examples/
│   └── usage-example.sh              # Complete workflow demo
└── references/
    └── nix-package-format.md         # Nix package structure reference

Examples

See examples/usage-example.sh for a complete workflow demonstration.

Security

• All scripts validate input formats before execution
• File modifications are atomic (all-or-nothing)
• No partial updates - failures abort before system changes
• Dry-run mode available for safe preview

License

Part of the AI Skills collection. See repository root for license information.