How it works

1. Internal skills context

When Internal Skills Context is enabled, the plugin prepends hidden skills guidance before the current user message reaches the model.

The internal context is routed, not a broad skill dump. The plugin scores skill metadata against the current request and injects only the top routed candidates:

<skills_runtime_context>
...
</skills_runtime_context>

<routed_skills>
  <skill rank="1" confidence="high" score="86">
    <n>skill-name</n>
    <description>...</description>
    <why>frontmatter:description_token=...</why>
    <environment>WSL</environment>
    <location>WSL:/home/user/.agents/skills/skill-name/SKILL.md</location>
  </skill>
</routed_skills>

To avoid context overload, the plugin injects:

• routed context when there is a confident route,
• routed context when the route changes or refreshes,
• a compact reminder when no skill is confidently routed,
• no broad catalog of all installed skills.

Manual system-prompt instructions are optional and should only be used for extra project-specific behavior beyond the plugin defaults.

2. Explicit skill activation

Users can explicitly activate a skill in a prompt with $skill-name notation:

Use $example-skill to create the helper.

When the preprocessor sees $example-skill, it resolves that skill directly and expands the matching SKILL.md body into a <skill_invocation_packet> before the request reaches the model.

Explicit activations tell the model:

• the named skill is intentional and should be treated as the highest-priority skill context for the request,
• the matching SKILL.md body has already been expanded into a <skill_invocation_packet> before model reasoning,
• all other user text is secondary task payload for that skill,
• quoted strings, backticked snippets, globs, and command-looking text must not be interpreted before applying the expanded skill,
• run_command must not be used for exploration,
• unresolved $skill tokens should be searched with list_skills before proceeding.

The notation accepts lowercase skill-like names beginning with a lowercase letter and containing lowercase letters, numbers, ., _, or -. Uppercase shell variables such as $HOME are ignored so command payloads are not misread as skill activations. Examples:

$docx
$example-skill
$my.custom_skill

Explicit activation works even when the regular internal context is disabled, because the user is directly asking for a skill by name. Unlike normal routed candidates, explicit activations expand the selected SKILL.md body immediately; normal routing still uses progressive disclosure and expects the model to call read_skill_file for routed candidates. For explicit activations, the preprocessor removes the $skill-name token from the model-facing task payload and wraps the remaining user text in <task_payload for_expanded_skills="..."> so the model applies the expanded skill before interpreting command-looking text.

3. Skill tools

4. Runtime environments

The plugin can resolve skills in different filesystem/runtime environments:

Environment-labeled paths look like:

Windows:C:\Users\you\.lmstudio\skills\docx\SKILL.md
WSL:/home/you/.agents/skills/docx/SKILL.md

Skill directory structure

A skill is any subdirectory inside a configured skills path that contains a SKILL.md file.

~/.lmstudio/skills/
├── docx/
│   ├── SKILL.md             # entry point, required
│   ├── scripts/
│   │   └── helper.py
│   └── templates/
│       └── base.docx
├── pptx/
│   ├── SKILL.md
│   └── editing.md
└── my-custom-skill/
    ├── SKILL.md
    └── skill.json           # optional metadata override

SKILL.md

SKILL.md is the required entry point for a skill. Claude-style YAML frontmatter at the top of SKILL.md is used as high-level routing metadata for <routed_skills>.

---
name: example-skill
description: Use this skill when the user needs a clear, complete example workflow.
when_to_use: Trigger when the request matches the workflow this skill implements.
tags: [examples, workflow]
disable-model-invocation: false
---

# Example Skill

Detailed instructions go here. This body is loaded when the model calls `read_skill_file`.

Frontmatter behavior:

• name overrides the directory name in high-level context.
• description is the primary trigger text shown to the model before it reads the full skill.
• when_to_use / when-to-use is appended to description in the high-level skill listing.
• tags are used for search/scoring.
• disable-model-invocation: true keeps the skill out of automatic routing context, while still allowing explicit $skill-name activation.
• Descriptions are capped at 1,536 characters to keep high-level context useful without loading the full skill body.
• The frontmatter is stripped from read_skill_file results for SKILL.md, so the model receives the detailed instruction body after discovery metadata has already been consumed.

This mirrors the progressive-disclosure pattern: lightweight frontmatter is used for routing, normal routed skills load their body through read_skill_file, and explicit $skill-name activations expand their matching body immediately.

skill.json optional legacy metadata

Place skill.json in a skill directory to override display metadata when SKILL.md frontmatter is absent:

{
  "name": "My Custom Skill",
  "description": "Use this skill when the user asks to do X, Y, or Z.",
  "tags": ["data analysis", "csv", "statistics"]
}

Metadata priority is: SKILL.md frontmatter first, then skill.json, then the directory name plus the first paragraph of the markdown body.

Deterministic skill routing

The model should not scan a long skills catalog. The plugin routes before injection so the model sees only the smallest useful set of candidates.

Routing uses metadata only:

name
directory basename
frontmatter description
frontmatter when_to_use / when-to-use
tags
environment/display path

The router scores exact name matches, tag matches, description/when-to-use token overlap, and path/name overlap. Skills with disable-model-invocation: true are excluded from automatic routing. For normal routed candidates, the full SKILL.md body is not injected; the model loads it with read_skill_file. For explicit $skill-name activation, the matching SKILL.md body is expanded immediately before the model starts reasoning.

Use list_skills with mode: "route" to inspect the same routing decision outside the prompt loop.

Settings

Skills paths

• Empty — use the last saved paths, or ~/.lmstudio/skills on first run.
• default — reset saved paths back to ~/.lmstudio/skills.
• Semicolon-separated paths — load multiple roots in order.

Examples:

~/.lmstudio/skills
~/.agents/skills
~/.lmstudio/skills;~/.agents/skills

Settings are persisted to:

~/.lmstudio/plugin-data/lms-skills/settings.json

Tool input schemas

All plugin tools use Zod schemas before the implementation runs. These schemas reject malformed inputs early, including:

• empty required fields,
• overly long skill names, paths, queries, commands, and environment values,
• control characters and null bytes,
• path traversal such as .. in skill-relative file paths,
• absolute paths where a skill-relative path is required,
• invalid command timeout ranges,
• unsafe environment variable names or oversized environment maps.

Schema validation is not the only safety layer. Runtime path checks, command safety policy, and request timeouts still run after schema validation.

Command execution safety

run_command is intentionally disabled by default.

This prevents the model from issuing exploratory or destructive shell commands unless the user explicitly enables command execution in plugin settings.

Read-only mode allows inspection-style commands such as:

pwd, ls, cat, head, tail, grep, rg, find, stat, file, wc, sort, diff, env, which

The safety policy blocks destructive or high-risk patterns such as:

rm, rmdir, del, Remove-Item
format, mkfs, dd, shred
chmod, chown, chgrp
mv, cp, mkdir, touch, tee
redirection such as >, >>, <<
package managers such as npm install, pip install, apt, brew, choco
network/download tools such as curl, wget, Invoke-WebRequest
ssh, scp, rsync
mutating git commands such as clone, pull, push, reset, clean, checkout
kill/taskkill
nested shells such as bash -c, sh -c, powershell -c
encoded PowerShell

This is policy-level hardening, not a full OS sandbox. For untrusted workloads, use an external sandbox such as a container, VM, or locked-down WSL environment with read-only mounts, no network, and resource limits.

Timeout guardrails

The plugin has layered timeout protection so model/tool requests cannot wait forever:

Timeouts are enforced with AbortSignal, so WSL/runtime subprocesses are killed when possible. Timeout events are logged as tool_timeout or runtime_exec_abort.

Diagnostics

The plugin emits concise structured logs prefixed with [lms-skills].

Default logs are human-readable route, context-injection, and tool summaries. Every prompt injection logs proof of what was inserted, including injection kind, selected/expanded skills, source paths, byte counts, short SHA-256 hashes, and compact previews:

[lms-skills] prompt activation tokens=$example-skill resolved=example-skill unresolved=- expanded=1 action=expanded_before_model id=prompt-...
[lms-skills] route mode=explicit_activation_expanded action=expanded_skill(example-skill) before_model inject=1984ch id=prompt-...
[lms-skills] context kind=explicit_expanded packet=skill_invocation_packet skills=example-skill inject=1984ch sha=85a3f72de1cd preview="<skill_invocation_packet ..." payload=67ch payloadSha=678f53749760 payload="..." id=prompt-...
[lms-skills] context kind=routed packet=routed_skills skills=1:docs-writer:score=128:confidence=high:source=WSL:/... inject=1378ch sha=d0abcc393a31 payload="please update the README docs" id=prompt-...
[lms-skills] read_skill_file start skill=example-skill file=- timeout=30000ms id=read_skill_file-...
[lms-skills] read_skill_file done 42ms id=read_skill_file-...

The context line is the audit trail for model-facing context. Use it to verify whether the model received an explicit expanded skill packet, routed skill candidates, a compact reminder, or fallback context.

Set LMS_SKILLS_DEBUG=1 to switch back to full JSON event logs.

Enable verbose step/runtime tracing with:

LMS_SKILLS_DEBUG=1 npm run dev

Optional thresholds:

LMS_SKILLS_SLOW_STEP_MS=250
LMS_SKILLS_SLOW_RUNTIME_MS=500

Default skills path by platform

The default path ~/.lmstudio/skills resolves to:

In WSL mode, ~ is resolved using the WSL/Linux home directory.

Model workflow

• User sends a message.
• The prompt preprocessor checks for explicit $skill-name tokens.
• If present, the plugin resolves the exact skill and expands the stripped SKILL.md body into a <skill_invocation_packet> before model reasoning.
• If no explicit activation exists, the deterministic router scores skill metadata and injects up to three routed candidates, or only a compact reminder when no route is confident.
• For routed candidates, the model calls read_skill_file("skill-name") before doing covered work.
• The model follows SKILL.md; if needed, it calls list_skill_files and reads referenced supporting files.
• Shell commands are blocked unless command execution has been explicitly enabled.

Local development

cd lms-plugin-skills
bun install
bun run dev

Equivalent npm commands usually work too:

npm install
npm run build
npm run dev

Verification

npm run build

No test suite is currently configured.

License

Apache 2.0