name	checking-files-with-lsp
description	Use when you need to check, verify, validate or understand code or structure of a file (often code related files or markdown) - automatically detects file type, finds appropriate LSP/linter in mise, and runs validation

Checking Files With LSP

Overview

When you need to validate, check, or understand a file's structure or code quality, use language servers and linters to do it systematically. This skill provides a reliable workflow: detect the file type, search mise for available LSP/linter tools, intelligently choose one, and run the check.

Core principle: Let the appropriate tool for the language do the validation work, not manual inspection. Automate tool discovery and selection.

When to Use

Use this skill when:

Checking code files for syntax errors, type issues, or style problems
Validating configuration files (YAML, TOML, JSON, KDL, etc.)
Understanding code structure or quality of unfamiliar files
Verifying Markdown files for formatting/link issues
Need to quickly understand what problems exist in a file

Don't use when:

Just reading a file to understand its contents (no validation needed)
Running full test suites (that's testing, not validation)
Analyzing code behavior (that's debugging, not validation)

The Workflow

Step 1: Detect File Type

Determine the language/type from file extension:

.lua     → lua
.ts/.tsx → typescript
.py      → python
.go      → go
.rs      → rust
.md      → markdown
.json    → json
.yaml    → yaml
.toml    → toml
.kdl     → kdl

If extension is unclear or missing, inspect file shebang or content patterns.

Step 2: Search Mise for LSP/Linters

Run: mise search <filetype>

This returns all available language servers, linters, and formatters for that language.

Example outputs:

mise search lua
lua-language-server    (most popular)
stylua                 (formatter)

mise search python
pyright
pylance
python-language-server
black
ruff

Step 3: Make Smart Selection

Prioritize by tool type: Language Server (LSP) > Linter > Formatter

LSPs provide the most comprehensive validation. Linters catch style/quality issues. Formatters are secondary for validation purposes.

If ONE obvious choice exists:

Auto-select it (e.g., only lua-language-server for Lua)
Verify installation: mise list | grep <tool> (if not listed, install it)
Install: mise install lua-language-server
Run it on the file

If MULTIPLE choices exist:

Filter by priority: Show LSPs first, linters second, skip formatters
Rank by popularity: Most-used tools first (measured by GitHub stars, then npm/PyPI downloads as tiebreaker)
Show ranked list to user (with tool type and brief descriptions)
Let user pick by number/letter
Verify and install selected tool
Run it on the file

If NO tools found:

Inform user explicitly: "No LSP/linter available in mise for [filetype]"
Suggest alternatives in order:
1. Check online package managers (npm, PyPI, cargo, etc.) if not in mise
2. Look for generic validators (jq for JSON, yamllint for YAML, etc.)
3. Basic syntax checking (built-in language checkers)
4. Manual validation with structured guidance
Offer: "Would you like me to help install from another source?"

Step 4: Run Validation

Execute the selected tool against the file and return results: errors, warnings, style issues, and suggestions.

Quick Reference

Task	Action
Detect file type	Use file extension as primary signal
Find tools	`mise search <filetype>`
Install obvious choice	`mise install <tool>` (auto-selected)
Show options	Present ranked list for user choice
Run validation	Execute tool with file path

Common Mistakes

Mistake: Skip file type detection

Wrong: "It's a code file, any language server works"
Right: File type determines which LSP applies. Wrong LSP = wrong errors

Mistake: Pick random LSP when multiple exist

Wrong: "I'll just try the first one" or "They're all the same"
Right: Different LSPs check different aspects. Use ranking: most popular > less common. Filter by type: LSP > Linter > Formatter
No exceptions: You must present options to user when multiple exist, not guess

Mistake: Assume LSP is installed

Wrong: "Let me just run lua-language-server..."
Right: Always verify with mise search first. Check mise list before installing. Install if needed

Mistake: Don't check system requirements

Wrong: "Install the LSP and it'll work"
Right: Some LSPs need runtime dependencies (Python, Node, etc.). Test LSP runs before reporting results

Mistake: When LSP unavailable, give up

Wrong: "No tool for this language, can't validate"
Right: Explore alternatives in order: online package managers → generic validators → syntax checking → manual guidance

Mistake: Mixing tool categories

Wrong: Showing formatters and linters equally for validation
Right: Prioritize LSP > Linter > Formatter. Use tool type as first filter

Fallback Validation Options

When LSP/linter not available in mise:

Check online package managers (npm, PyPI, cargo, etc.) if not in mise
Look for generic validators - JSON validators, YAML checkers work across projects
Basic syntax checking - Some languages have built-in syntax checkers
Manual validation - Provide structured review guidance
Suggest installation - "Would you like me to help install from another source?"

Implementation Steps

When helping a user check a file:

Ask or determine: "What file are we checking?"
Detect the file type from extension
Run: mise search <filetype>
Decide: obvious choice or show ranked options?
Verify installation: mise list | grep <tool> (check if already installed)
Install if needed: mise install <selected-tool>
Test tool runs: Verify LSP/linter executes without errors
Run: Execute tool against file with appropriate flags
Report: Show user the validation results
Offer next steps: "Fix these issues?" or "Run checks again?"

Troubleshooting

Tool installs but won't run:

Some LSPs need runtime dependencies (Python for some tools, Node for others)
Check LSP documentation for runtime requirements
Example: python-language-server needs Python installed
Verify with: mise exec <tool> -- <tool> --version

Mise search returns no results:

Language might not be in mise database
Try alternative package managers: npm (JavaScript), PyPI (Python), cargo (Rust)
Or use generic validators: jq (JSON), yamllint (YAML)

LSP finds errors but tool isn't right for the job:

Wrong tool selected (formatter instead of LSP)
Go back to Step 3, filter by type priority (LSP > Linter)
Ask user to pick a different option from the list

File has unusual extension:

Use file content inspection (shebang, headers) as fallback
Example: Executable shell scripts often lack .sh extension
Check content to confirm type before searching mise

Real-World Impact

Fast validation: No manual code review for common issues
Consistent checking: Same tool, same criteria, every time
Discovery: Find issues you'd miss with manual inspection
Automation: Can be integrated into workflows, CI/CD, pre-commit hooks
Language agnostic: Same pattern works for any language with an LSP available

checking-files-with-lsp

Install Skill

SKILL.md