--- name: add-nixvim-plugin description: Add Neovim plugins not available in NixVim's official plugin set using extraPlugins and extraConfigLua. Use this skill when the user requests adding a plugin by GitHub URL or mentions a plugin that doesn't exist as a native NixVim module. --- # Add NixVim Plugin ## Overview Add custom Neovim plugins to NixVim using `extraPlugins` when the plugin isn't available in NixVim's official plugin set. This skill guides through fetching plugin information, creating configuration files, and maintaining consistency with the existing plugin structure. ## When to Use This Skill Use this skill when: - User provides a GitHub URL for a Neovim plugin - User requests a plugin that doesn't have a native NixVim module (e.g., `plugins.plugin-name`) - User asks how to add plugins not in NixVim Do NOT use this skill when: - The plugin already has native NixVim support (use the standard `plugins.plugin-name` configuration) - User is asking about configuring an already-added plugin ## Workflow ### Step 1: Gather Plugin Information Fetch information about the plugin from its GitHub repository: 1. Use WebFetch to visit the plugin's GitHub URL 2. Extract: - Plugin purpose and key features - Default configuration structure - Any setup requirements - Latest stable commit hash or release tag ### Step 2: Determine Plugin Category Identify the appropriate subdirectory in `config\/plugins\/`: - `ui\/` - UI enhancements, windows, buffers - `editing\/` - Text editing, manipulation - `lsp\/` - Language server related - `navigation\/` - Movement, jumping - `git\/` - Git integration - `files\/` - File management - `completion\/` - Completion engines - `search\/` - Search and replace - `terminal\/` - Terminal integration - `workflow\/` - Productivity, helpers - `testing\/` - Test frameworks - `statusline\/` - Status line plugins - `treesitter\/` - Treesitter related - `snippets\/` - Snippet engines - `ai\/` - AI assistants - `langs\/` - Language-specific ### Step 3: Create Plugin Configuration File Create `config\/plugins\/\/.nix` with this structure: ```nix # ABOUTME: [Brief description of what the plugin does] # ABOUTME: [Secondary description line if needed] {pkgs, ...}: { extraPlugins = [ (pkgs.vimUtils.buildVimPlugin { name = "plugin-name"; src = pkgs.fetchFromGitHub { owner = "github-username"; repo = "repo-name"; rev = "commit-hash-or-tag"; sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Use fake hash initially }; }) ]; extraConfigLua = '' require("plugin-name").setup({ -- Start with minimal default configuration -- Add essential settings only }) ''; keymaps = [ { mode = "n"; key = "xy"; action = "PluginCommand"; options = { desc = "Brief description"; silent = true; }; } ]; } ``` **Important notes:** - Start with fake SHA256 hash - Nix will provide correct hash on first build - Follow existing keymap groups (`f` = file, `u` = UI, `w` = window, etc.) - Keep initial configuration minimal - add incrementally as needed - Include ABOUTME comments at the top of the file ### Step 4: Update default.nix Add the new plugin file to `config\/default.nix` imports in the appropriate section: ```nix { imports = [ # ... other imports .\/plugins\/\/.nix ]; } ``` Maintain alphabetical or logical ordering within each section. ### Step 5: Update Documentation Update three locations to document the new plugin: #### 5a. Update recent_plugins in config\/options.nix Add entry at the TOP of the `recent_plugins` table (around line 96): ```lua { name = "plugin-name", date = "YYYY-MM-DD", -- Today's date description = "Brief description of functionality", keymaps = { "xy = Action Description", -- additional keymaps }, usage = "How to use the plugin, key features" }, ``` #### 5b. Add whichkey entries in config\/plugins\/workflow\/whichkey.nix Add entries to the `spec` array for each keymap: ```nix { "__unkeyed-1" = "xy"; desc = "Action Description"; icon = { icon = "󰈙"; # Choose appropriate Nerd Font icon color = "blue"; # Choose appropriate color }; } ``` Icon colors available: blue, yellow, orange, cyan, purple, green, red, azure #### 5c. Update WISHLIST.md (if applicable) If the plugin was on the wishlist, mark it as completed or remove the entry. ### Step 6: Build and Test 1. Stage files: `git add .` (required for Nix flakes) 2. Build: `nix build` or `just build` 3. If SHA256 hash error occurs: - Copy correct hash from error message - Update the config file with correct hash - Build again 4. Test: `nix run .` or `just run` ### Step 7: Lazy Loading (Optional) If the plugin should be lazy-loaded to improve startup time: 1. Read `references\/lazy-loading.md` for detailed patterns 2. Modify the plugin configuration to use lz.n 3. Test that the plugin loads correctly when triggered Common lazy-loading scenarios: - Load on command: `cmd = "CommandName"` - Load on keypress: `keys = "key"` - Load on event: `event = "BufEnter"` - Load on filetype: `ft = "python"` ## Troubleshooting **Build fails with "file not found"** - Ensure `git add .` was run before building - Nix flakes only see tracked files **Wrong SHA256 hash error** - Expected on first build - Copy correct hash from error message - Update config file and rebuild **Plugin not loading** - Check plugin is imported in `config\/default.nix` - Verify `extraConfigLua` has no syntax errors - Ensure plugin name matches exactly (case-sensitive) **Formatter changes files** - Pre-commit hooks with alejandra automatically format Nix files - This is expected behavior ## Resources See `references\/lazy-loading.md` for detailed lazy loading configuration patterns.