Skill: ivangdavila/lm-studio (version 1.0.0)

--- name: LM Studio slug: lm-studio version: 1.0.0 homepage: https://clawic.com/skills/lm-studio description: Run and integrate LM Studio with local model lifecycle control, OpenAI-compatible APIs, embeddings, and MCP-aware workflows. changelog: Initial release with local server workflows, model lifecycle checks, API recipes, MCP guidance, and troubleshooting for LM Studio. metadata: {"clawdbot":{"emoji":"🧪","requires":{"bins":["curl","jq"]},"os":["linux","darwin","win32"],"configPaths":["~/lm-studio/"]}} --- ## When to Use User wants to run local models with LM Studio, connect an app to its local server, or debug weak local inference behavior. Use this for server readiness, model loading, OpenAI-compatible API integration, embeddings, MCP setup, and local-first operating decisions. ## Architecture Memory lives in `~/lm-studio/`. If `~/lm-studio/` does not exist, run `setup.md`. See `memory-template.md` for structure. ```text ~/lm-studio/ ├── memory.md # Activation, preferred port, known-good defaults ├── server-notes.md # Reachability checks and server mode notes ├── model-profiles.md # Verified models by workload └── incidents.md # Repeated failures and confirmed fixes ``` ## Quick Reference | Topic | File | |-------|------| | Setup behavior and activation boundaries | `setup.md` | | Memory schema and status states | `memory-template.md` | | Server startup and smoke tests | `server-workflows.md` | | Download, load, unload, and swap models | `model-lifecycle.md` | | OpenAI-compatible request patterns | `api-recipes.md` | | MCP connection patterns and guardrails | `mcp-playbooks.md` | | Symptom-based debugging | `troubleshooting.md` | ## Requirements - LM Studio or `llmster` is already installed on the machine. - `curl` and `jq` are available for smoke tests and response inspection. - `lms` is optional but preferred for repeatable server and model operations. - Keep requests local by default; only add remote MCP servers or network exposure when the user explicitly asks. ## Core Rules ### 1. Prove the server is reachable before changing client code - Use `server-workflows.md` to confirm the actual port, endpoint reachability, and model visibility. - "LM Studio is open" is not enough. Require one real request to succeed before touching integration code. ### 2. Separate downloaded, listed, loaded, and active models - Use `model-lifecycle.md` for discovery, loading, unloading, and verification. - Never assume a downloaded filename, API model id, CLI identifier, and active runtime instance are the same thing. ### 3. Prefer OpenAI-compatible endpoints for app integration - Start from `api-recipes.md` and change only the base URL and model identifier before rewriting an existing client. - Verify each workload separately: `responses`, `chat/completions`, `embeddings`, or `completions`. ### 4. Match model size and context to machine limits - Treat slow first token, OOM, and context overflow as runtime-fit problems first, not prompt problems first. - Reduce model size, quantization burden, or context length before escalating complexity. ### 5. Validate after every runtime change - After loading a new model, changing context length, or altering server settings, run one end-to-end smoke test. - Record the known-good combination in memory so the agent can reuse it instead of rediscovering it. ### 6. Treat MCP as a separate risk layer - Use `mcp-playbooks.md` to connect servers, but debug model serving and MCP behavior independently. - Never install untrusted MCP servers or silently route local data to remote endpoints. ### 7. Escalate beyond local when the task exceeds the local setup - LM Studio is strong for privacy-sensitive work, offline execution, extraction, and controlled agent loops. - For unsupported capabilities or repeated quality failures, say so explicitly and recommend a stronger remote path. ## Common Traps - Assuming port `1234` without checking reachability -> integrations fail even though the app looks healthy. - Treating `GET /v1/models` as proof a model is ready -> Just-In-Time listings can appear before a usable runtime is confirmed. - Reusing cloud model names in local requests -> the client is fine, but the local model identifier is wrong. - Forcing JSON, tools, or vision on an unverified local model -> failures get blamed on prompts instead of capability mismatch. - Leaving large models loaded while debugging another issue -> RAM or VRAM pressure hides the real cause. - Installing random MCP servers -> privacy and system access boundaries disappear quickly. ## Security & Privacy Data that leaves your machine: - None by default for local `localhost` server calls. - Optional model downloads or MCP servers follow the user's explicit configuration, not this skill's default path. Data that stays local: - Prompt content sent to the LM Studio server running on the same machine. - Notes stored in `~/lm-studio/` if the user wants persistent context. This skill does NOT: - Assume remote access is safe by default. - Store secrets in skill memory files. - Install MCP servers or open network access without explicit user intent. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `models` — Choose models by workload, context budget, and quality tradeoffs. - `api` — Shape request payloads, retries, parsing, and integration debugging. - `self-host` — Operate local infrastructure with practical reliability and security habits. - `open-router` — Escalate from local-first execution to routed cloud models when capability gaps matter. - `docker` — Package helper services or MCP servers consistently on the local machine. ## Feedback - If useful: `clawhub star lm-studio` - Stay updated: `clawhub sync`

path: api-recipes.md
content: # API Recipes — LM Studio

LM Studio exposes OpenAI-compatible endpoints. Reuse existing clients by changing the base URL and replacing the model identifier with one from the local runtime.

Supported local endpoints include:
- `GET /v1/models`
- `POST /v1/responses`
- `POST /v1/chat/completions`
- `POST /v1/embeddings`
- `POST /v1/completions`

Assume port `1234` only until a reachability check proves it.

## 1. Python Client

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:1234/v1")
```

Then keep the rest of the client mostly the same, but replace:
- Remote model names.
- Unsupported request fields.
- Assumptions that the local model supports every OpenAI feature.

## 2. TypeScript Client

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:1234/v1",
});
```

Before shipping, verify one real request with the intended local model id.

## 3. Chat Completions Smoke Test

```bash
curl -fsS http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_LOCAL_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Be concise."},
      {"role": "user", "content": "Reply with READY."}
    ],
    "temperature": 0
  }' | jq .
```

Use this first when migrating an existing app from a cloud provider.

## 4. Responses Endpoint

LM Studio also supports the OpenAI-compatible `responses` endpoint, which matters for tools that expect it.

```bash
curl -fsS http://localhost:1234/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_LOCAL_MODEL_ID",
    "input": "Reply with READY."
  }' | jq .
```

Use this if the client, agent framework, or tool already depends on `responses`.

## 5. Embeddings Smoke Test

```bash
curl -fsS http://localhost:1234/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_LOCAL_EMBEDDING_MODEL_ID",
    "input": ["local embedding test"]
  }' | jq '.data[0].embedding | length'
```

Do not assume a chat model is also the correct embedding model.

## 6. Migration Checklist

When moving an existing OpenAI-based integration to LM Studio:
1. Change the base URL.
2. Replace the model name with a local identifier.
3. Remove unsupported request fields if the first request fails.
4. Verify the exact endpoint you plan to use.
5. Add a timeout and a friendly failure path for when the local server is down.

## 7. Failure Patterns

- `404` or `connection refused` -> wrong base URL or server not listening.
- `model not found` -> cloud model name still hardcoded.
- Empty or weak structured output -> wrong local model for the task, not necessarily wrong prompts.
- Slow requests after a machine sleep or heavy run -> re-check server readiness and loaded-model state.


path: mcp-playbooks.md
content: # MCP Playbooks — LM Studio

Treat MCP as a separate layer on top of model serving. A bad MCP setup can look like a model problem even when the model is fine.

## 1. When MCP Belongs Here

Use MCP with LM Studio when the user wants:
- Local models plus tools.
- A desktop chat workflow with external capabilities.
- A controlled local-first agent loop where model serving stays separate from tool access.

Do not introduce MCP just because the model is weak. Fix the model path first.

## 2. Basic Connection Flow

Inside LM Studio, MCP servers are configured through `mcp.json`.

High-level process:
1. Add the server definition.
2. Confirm the model still behaves normally without tools.
3. Re-enable the MCP server.
4. Run one focused tool-use test.

That split matters. It tells you whether the failure lives in the model or in the tool layer.

## 3. Manual JSON Pattern

The docs show an `mcpServers` object in `mcp.json`.

Use this mental model:
- Each server entry is explicit.
- Remote URLs and headers are part of the server definition.
- Copy only the server object content that belongs inside `mcpServers`.

Never paste random full JSON blobs into the wrong nesting level.

## 4. Security Boundary

Some MCP servers can:
- Run arbitrary code.
- Access local files.
- Use the network.

Rules:
- Never install MCP servers from untrusted sources.
- Never assume a server is safe because it is popular.
- If the MCP is remote, state clearly that data can leave the machine.

## 5. Token and Context Pressure

Some MCP servers were designed for larger frontier models and can overwhelm smaller local models.

Watch for:
- Context overflows.
- Very slow turns after tool injection.
- Tool descriptions that consume too much prompt budget.

If that happens:
- Reduce tool surface area.
- Use a stronger local model.
- Or keep MCP off for that task.

## 6. Minimal Test Pattern

After enabling MCP:
1. Ask the model to describe which tool it intends to use.
2. Run one small tool request.
3. Confirm the tool output is grounded and complete.
4. Repeat only after the first success.

Avoid multi-tool agent loops until the first small test passes.

## 7. Debugging Split

Use this order:
- Model works without MCP?
- MCP server loads cleanly?
- Tool call works once?
- Multi-step loop works?

Only move to the next layer after the current one passes.


path: memory-template.md
content: # Memory Template — LM Studio

Create `~/lm-studio/memory.md` with this structure:

```markdown
# LM Studio Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | complete | paused | never_ask

## Activation
- Auto-activate when:
- Explicit-only topics:
- Never activate for:

## Runtime Baseline
- OS:
- Hardware constraints:
- Preferred port:
- Server mode: app | llmster | undecided
- CLI available: yes | no

## Verified Models
- Chat:
- Coding:
- JSON or structured output:
- Embeddings:

## Known Good Checks
- Smoke test:
- Known-good context length:
- GPU preference:

## Incident Notes
- Date:
- Symptom:
- Root cause:
- Confirmed fix:

## Notes
- Stable user preference:
- Follow-up:

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Context still evolving | Keep learning from real LM Studio tasks |
| `complete` | Baseline is stable | Execute directly with minimal setup questions |
| `paused` | User paused extra profiling | Use the current baseline without pushing |
| `never_ask` | User opted out of setup | Never request setup context again |

## Principles

- Store verified runtime facts and outcomes, not vague guesses.
- Never store tokens, passwords, or copied credentials.
- Update `last` after meaningful runtime or model changes.
- Prefer short incident notes tied to one confirmed fix.


path: model-lifecycle.md
content: # Model Lifecycle — LM Studio

This is the operating model: discover, load, verify, use, unload.

## 1. Discover What Exists

If `lms` is available:

```bash
lms ls
```

If the local server is reachable:

```bash
curl -fsS http://localhost:1234/v1/models | jq '.data[].id'
```

Important:
- Disk inventory is not runtime readiness.
- The server list can include models visible for Just-In-Time loading.
- A model name in the UI is not automatically the identifier you should hardcode into app code.

## 2. Load a Model Intentionally

Use explicit load commands when you want deterministic control:

```bash
lms load openai/gpt-oss-20b --identifier="local-chat"
```

Useful options from the CLI docs:

```bash
lms load [--gpu=max|auto|0.0-1.0] [--context-length=1-N]
```

Use cases:
- `--gpu=max` when the machine should use as much GPU offload as possible.
- `--gpu=auto` when you want the runtime to choose.
- `--context-length` when long contexts are pushing the machine too hard.

## 3. Verify the Loaded Runtime

After loading, verify with both the CLI and the API:

```bash
lms ps
curl -fsS http://localhost:1234/v1/models | jq '.data'
```

Then run one inference smoke test before declaring the model ready.

## 4. Match Workload to Model Reality

Use this progression instead of jumping to the largest model:

- Extraction, classification, summarization -> start small and fast.
- Day-to-day chat or agent loops -> use the smallest model that stays coherent on the real task.
- Coding or structured output -> verify with task-specific smoke tests before rollout.
- Embeddings -> use a model that is intended for embedding requests, not a chat model by assumption.

If a model fails a basic workload, downgrade the ambition or switch models early.

## 5. Unload on Purpose

When debugging performance or freeing memory:

```bash
lms unload --all
```

Then confirm the machine is actually clear:

```bash
lms ps
```

Unload before comparing models. Otherwise leftover memory pressure corrupts the test.

## 6. Stable Identifier Strategy

If the user wants repeatable app wiring, give the loaded model a stable identifier.

Why:
- The downloaded model name can change across pulls.
- A stable identifier makes app config and smoke tests cleaner.
- Swapping the backing model later becomes safer.

## 7. What to Record After a Good Run

Store only facts that help future work:
- Model identifier that passed.
- Context length that stayed stable.
- Whether GPU offload helped or hurt.
- Which workloads the model passed or failed.


path: server-workflows.md
content: # Server Workflows — LM Studio

Use these workflows to prove the local runtime is actually ready before touching app code.

## 1. Quick Reachability Check

Start with the OpenAI-compatible model listing endpoint:

```bash
curl -fsS http://localhost:1234/v1/models | jq .
```

Interpretation:
- Success with model data -> the server is reachable.
- Connection refused or timeout -> the local server is not listening on that port.
- Empty or unexpected response -> check whether the local server is enabled and whether the port changed.

## 2. CLI-First Server Control

If `lms` is available, use it for repeatable checks:

```bash
lms server start
lms server stop
```

When the server is running, keep the CLI and HTTP checks separate:
- CLI proves the LM Studio side started.
- `curl` proves the client path and port are correct.

## 3. Inventory vs Runtime State

Use these commands in order:

```bash
lms ls
lms ps
curl -fsS http://localhost:1234/v1/models | jq '.data[].id'
```

Read them differently:
- `lms ls` -> what exists locally on disk.
- `lms ps` -> what is currently loaded.
- `/v1/models` -> what the local server advertises to clients.

Do not collapse those into one concept.

## 4. Minimal Smoke Test

After the port responds, prove inference works:

```bash
curl -fsS http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_LOCAL_MODEL_ID",
    "messages": [
      {"role": "user", "content": "Reply with the word READY."}
    ],
    "temperature": 0
  }' | jq -r '.choices[0].message.content'
```

Only move on after the model returns content.

## 5. If the App Is Open but Requests Fail

Check these in order:
1. Wrong port.
2. Local server not enabled.
3. Model not loaded yet.
4. Machine slept and the local runtime lost readiness.
5. Client is pointing at the wrong base URL.

## 6. Headless and No-GUI Mode

LM Studio also supports headless operation through `llmster`.

Use that path when:
- The machine has no desktop session.
- You want a server or CI-friendly runtime.
- The GUI is not part of the workflow.

Keep the same verification sequence: start runtime, list models, run one smoke test.


path: setup.md
content: # Setup — LM Studio

Read this when `~/lm-studio/` does not exist or is empty. Help quickly and stay local-first unless the user clearly wants a remote path.

## Operating Attitude

Be practical and skeptical. Get one known-good server plus model plus smoke test working before expanding into MCP, embeddings, or agent workflows.

## Priority Order

### 1. First: Integration

Clarify when this skill should activate in future conversations.

- Should it activate for LM Studio, local models, localhost OpenAI-compatible endpoints, embeddings, or MCP work?
- Should it jump in proactively when a local model is slow, failing, or producing bad structured output?
- Which topics should stay explicit-only, such as paid providers or remote inference?

### 2. Then: Establish the Current Runtime

Collect only details that change the plan.

- Operating system and rough hardware limits.
- Whether LM Studio app, `llmster`, or `lms` is already available.
- Whether the main priority is privacy, speed, cost avoidance, or app integration.

### 3. Finally: Capture Stable Defaults

Store only reusable operating defaults.

- Preferred local port if not the default.
- Known-good model identifiers for chat, coding, JSON, or embeddings.
- Whether MCP is in scope now or should stay off by default.

## Boundaries

- Answer the immediate LM Studio problem first, then refine reusable defaults.
- Avoid long onboarding or tutorials the user did not ask for.
- Never mention internal setup files or memory mechanics in user-facing replies.

## What to Capture Internally

Keep compact notes in `~/lm-studio/memory.md`.

- Activation boundaries and proactive behavior preferences.
- Verified port, server mode, and smoke-test method.
- Known-good models by workload.
- Recurring failure patterns such as OOM, context overflow, bad JSON, or MCP overload.
- Remote-access and MCP trust boundaries.


path: troubleshooting.md
content: # Troubleshooting — LM Studio

Use symptoms to narrow the fault before changing prompts or rewriting app code.

## Symptom -> Likely Cause -> Exact Check -> Better Move

| Symptom | Likely Cause | Exact Check | Better Move |
|---------|--------------|-------------|-------------|
| Connection refused | Wrong port or server not listening | `curl -fsS http://localhost:1234/v1/models` | Start the server, confirm port, then retry |
| `/v1/models` works but inference fails | Model not actually ready for the target workload | Run a minimal chat smoke test | Load a verified model and test again |
| `model not found` | Remote model name still hardcoded | Inspect request payload and compare with local ids | Replace with the LM Studio identifier |
| First token is extremely slow | Model too large, bad GPU fit, or cold load | Check `lms ps`, current model, and load settings | Reduce model size, GPU burden, or context |
| Output is repetitive or low quality | Weak model, wrong quantization, or overloaded context | Test a shorter prompt and smaller context window | Switch models before over-tuning prompts |
| JSON mode is unreliable | Model was never verified for structured output | Run one tiny JSON-only smoke test | Pick a known-good model for structure-heavy work |
| Embeddings call fails | Wrong model type or endpoint mismatch | Test `POST /v1/embeddings` directly | Use an embedding-capable model id |
| Everything gets worse after enabling MCP | Tool descriptions or tool path overwhelm the local model | Disable MCP and rerun the same prompt | Reduce MCP scope or use a stronger model |

## Fast Debug Order

1. Reachability.
2. Correct base URL.
3. Correct model identifier.
4. Loaded runtime state.
5. Workload capability of the chosen model.
6. MCP or tool pressure.

Do not skip the early steps. Most failures happen there.

## When to Stop Blaming the Prompt

Stop prompt-tuning and change the runtime when:
- The same failure happens on tiny prompts.
- Multiple endpoints fail for the same model.
- The machine clearly cannot hold the model and context comfortably.
- Another verified model succeeds immediately.

## When to Escalate Beyond LM Studio

Escalate when:
- The task is high-stakes and repeated local attempts still fail.
- The needed capability is unsupported in the local stack.
- The user values accuracy more than local-only execution for this task.

Say that explicitly instead of pretending the local path is still the best choice.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)