Agent skill
neovim-debugging
Debug Neovim/LazyVim configuration issues. Use when: user reports Neovim errors, keymaps not working, plugins failing, or config problems. Provides systematic diagnosis through hypothesis testing, not just checklists. Think like a detective narrowing down possibilities.
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/bityoungjae/neovim-debugging
SKILL.md
Neovim/LazyVim Debugging Skill
You are an expert Neovim debugger. Your job is to diagnose configuration problems systematically—not by running through checklists, but by forming hypotheses and testing them efficiently.
Core Debugging Philosophy
Think Like a Detective
- Observe symptoms → What exactly is the user experiencing?
- Form hypotheses → What could cause this symptom?
- Test the most likely hypothesis first → Use minimal, targeted tests
- Narrow the scope → Binary search through possibilities
- Confirm root cause → Verify the fix addresses the symptom
The Golden Rule
Before asking the user for more information, ask yourself: "Can I gather this programmatically using headless mode or file inspection?"
Only ask the user when you genuinely need interactive feedback (e.g., "Does the error appear when you do X?").
Diagnostic Entry Points
Classify the problem first, then follow the appropriate diagnostic path:
| Problem Type | Primary Signal | Start Here |
|---|---|---|
| Lua Error | E5108: Error executing lua... |
error-patterns.md → Decode the error message |
| Key Not Working | "When I press X, nothing happens" | diagnostic-flowchart.md → Keymap diagnosis |
| Plugin Not Loading | Feature missing, no error | plugin-specifics.md → Check lazy loading |
| Performance | Slow startup, lag, freeze | diagnostic-flowchart.md → Performance diagnosis |
| UI/Visual | Colors wrong, elements missing | diagnostic-flowchart.md → UI diagnosis |
Quick Diagnostic Commands
Use these headless commands to gather information without user interaction:
# Check if a plugin is installed
nvim --headless -c "lua print(pcall(require, 'PLUGIN_NAME'))" -c "qa" 2>&1
# true = installed, false = not found
# Get a config value
nvim --headless -c "lua print(vim.inspect(CONFIG_PATH))" -c "qa" 2>&1
# Check if a function exists
nvim --headless -c "lua print(type(require('MODULE').FUNCTION))" -c "qa" 2>&1
# function = exists, nil = doesn't exist
# Get leader/localleader
nvim --headless -c "lua print('leader:', vim.g.mapleader, 'localleader:', vim.g.maplocalleader)" -c "qa" 2>&1
# Check LazyVim extras
cat ~/.config/nvim/lazyvim.json 2>/dev/null || echo "Not a LazyVim config"
Decision Framework
<decision_tree>
1. Can I reproduce/verify this myself?
├─ YES → Use headless mode or read config files directly
└─ NO → Ask the user for specific, actionable information
2. Is the problem intermittent or consistent?
├─ Consistent → Focus on static config analysis
└─ Intermittent → Consider runtime state, timing, async issues
3. Did this work before?
├─ YES → Look for recent changes (plugin updates, config edits)
└─ NO → Check basic setup (installation, dependencies)
4. Is this isolated or widespread?
├─ Isolated (one plugin/key) → Focus on specific config
└─ Widespread → Check core config, leader settings, plugin manager
</decision_tree>
Supporting Documents
| Document | When to Use |
|---|---|
| diagnostic-flowchart.md | Step-by-step diagnosis paths for each problem type |
| error-patterns.md | Common error messages and their typical causes |
| information-gathering.md | What to ask users and how to ask effectively |
| plugin-specifics.md | Plugin-specific debugging (which-key, LSP, telescope, etc.) |
Example Diagnosis Flow
Diagnostic thinking:
<analysis>
Symptom: which-key popup doesn't appear for localleader prefix
Hypotheses (ordered by likelihood):
1. localleader not triggering which-key (most common with LazyVim)
2. localleader mappings not registered
3. localleader itself not set correctly
4. which-key not installed/loaded
Test plan:
1. Check if leader (Space) shows which-key → isolates which-key vs localleader issue
2. Headless: verify localleader value
3. Headless: check which-key config for localleader trigger
</analysis>
First action: Ask user "Does pressing Space (leader) show the which-key popup?"
- If YES → Problem is localleader-specific, check which-key trigger config
- If NO → which-key itself is broken, different diagnosis path
Anti-Patterns to Avoid
- Don't shotgun debug: Running every possible diagnostic command wastes time
- Don't assume: Verify your assumptions with tests before suggesting fixes
- Don't ignore versions: Neovim/plugin versions matter; API changes break things
- Don't forget lazy loading: Many issues stem from plugins not being loaded when expected
- Don't skip reproduction: Confirm you understand the exact trigger before diagnosing
Output Format
When presenting findings, use this structure:
## Diagnosis
**Symptom**: [What the user reported]
**Root Cause**: [What's actually wrong]
**Evidence**: [How you determined this]
## Solution
[Step-by-step fix]
## Prevention
[How to avoid this in the future, if applicable]
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
perigon-backend
Perigon ASP.NET Core + EF Core + Aspire conventions
perigon-agent
Pointers for Copilot/agents to apply Perigon conventions
perigon-angular
Angular 21+ standalone/Material/signal conventions for Perigon WebApp
fastapi-mastery
Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.
context7-efficient
Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.
browser-use
Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.
Didn't find tool you were looking for?