| name | local-llm-troubleshooting |
| description | Use this skill when diagnosing local LLM startup speed, prompt latency, GGUF model loading, tokenizer/chat-template issues, Metal or CPU backend behavior, model selection problems, context-window limits, sampling settings, or API compatibility for OpenAI, LM Studio, Ollama, and MCP routes. |
Local LLM Troubleshooting
Triage Order
- Separate startup time from first-token latency and decode throughput.
- Identify the model path resolution mode: exact
.gguf path, directory scan, metadata catalog lookup, or remote/client alias.
- Check backend selection: Metal enabled/disabled, CPU SIMD path, thread count, and runtime profile.
- Check prompt rendering: system prompt, chat template, Thinking mode, Skills mode, stop sequences, and context length.
- Check sampling: temperature, top-p, top-k, repeat penalty, seed, and max tokens.
Useful Measurements
- startup: process start, model resolution, mmap open, GGUF parse, tokenizer build, weight setup
- prefill: rendered prompt tokens and prompt tokens per second
- decode: generated tokens and tokens per second
- session reuse: cached prompt tokens versus evaluated prompt tokens
Output
Give the likely cause first, then a short measurement plan, then the smallest command or option change that can confirm it.
Gotchas
- A direct
.gguf path can be much faster than --model-dir --model if the latter triggers recursive catalog discovery.
- Longer system prompts, Thinking rewrites, and loaded Skills increase prefill work even when model loading is unchanged.
- Session cache helps repeated chat turns, but only when clients send a stable
conversation_id with prompt caching enabled.
- Do not compare decode speed across prompts unless prompt length, max tokens, and sampling settings are comparable.
