Skills

Skills are reusable instruction bundles for LibreChat Agents. A skill is centered on a SKILL.md file: frontmatter describes when the skill should be used, and the markdown body gives the agent the procedure, rules, examples, or references to follow.

Skills are useful for repeatable work such as:

• Applying brand or writing guidelines
• Following internal review checklists
• Running a standard research workflow
• Priming a specialized tool workflow
• Packaging reusable scripts, references, and assets with an instruction file

LibreChat does not ship a skill library. Every skill comes from your own instance: written or uploaded in the UI, authored by an agent during a chat, mounted from the filesystem, or mirrored from a GitHub repository.

Enable Skills

The skills agent capability is enabled by default. Admins can remove it from the agents endpoint capability list to hide Skills from users.

endpoints:
  agents:
    capabilities:
      - 'deferred_tools'
      - 'execute_code'
      - 'file_search'
      - 'web_search'
      - 'artifacts'
      - 'subagents'
      - 'actions'
      - 'context'
      - 'skills'
      - 'memory'
      - 'ask_user_question'
      - 'tools'
      - 'chain'
      - 'ocr'

Role permissions control who can use, create, share, and publicly share skills. Using and creating skills are allowed by default; sharing and public sharing are off by default for non-admin roles. Admins change these from the admin settings in the Skills panel.

If the capability is disabled, or your role lacks the use permission, Skills does not appear in the side panel at all.

Use a Skill

Create a Skill

Open Skills from the side panel and use the + button, which offers two paths:

• Write skill instructions — a dialog with a name, a description, and the instruction body.
• Upload a skill — a .md, .zip, or .skill file that contains a SKILL.md.

An agent can also create a skill for you while it works, without going through this panel. See Runtime Skill Authoring.

Minimum SKILL.md:

---
name: brand-guidelines
description: Use when writing public-facing content that must follow the company voice and terminology.
---

# Brand Guidelines

Write in a concise, practical tone.
Prefer active voice.
Use product terminology consistently.

Frontmatter

Keys are matched case-insensitively, and boolean fields accept only true or false. Removing a boolean key on a later save clears it, so deleting disable-model-invocation restores model invocation.

Recognized frontmatter fields are type-checked. Unrecognized fields are preserved as bounded, JSON-safe metadata instead of making the Skill invalid; deeply nested or oversized extension values are still rejected.

Keep a model-invoked Skill's description at 250 characters or fewer and place its most important trigger phrases first. Longer descriptions can still be imported, but LibreChat truncates them in the model-visible catalog and logs a warning naming each affected Skill.

Naming and Size Limits

• name is required, must match ^[a-z0-9][a-z0-9-]*$, and is limited to 64 characters. It must be unique among your own skills; re-uploading an existing name fails with a conflict error instead of overwriting.
• Names cannot start with anthropic- or claude-, and cannot be exactly help, clear, compact, model, exit, quit, settings, anthropic, or claude. Those names would shadow real commands.
• description is required and limited to 1024 characters. Descriptions under 20 characters are accepted with a warning, because they rarely trigger reliably.
• The instruction body is limited to 100,000 characters.

Upload a Bundle

A .zip or .skill archive must contain SKILL.md at the archive root or exactly one folder deep. A single wrapping folder is stripped on import; deeper layouts are not discovered.

Import limits:

• Accepted extensions: .md, .zip, .skill.
• 50 MB per upload by default. Admins change this with fileConfig.skills.fileSizeLimit in librechat.yaml.
• Up to 500 entries per archive, and 10 MB per bundled file.
• A .md upload with no frontmatter name derives the skill name from the filename.
• Entries with unsafe paths, such as traversal or absolute paths, are reported as errors and skipped; the rest of the skill still imports.

Skills that come from DEPLOYMENT_SKILLS_DIR or GitHub Skill Sync are read-only. Only skills authored inside LibreChat can be edited in the UI.

Invocation Modes

Skills can reach an agent in three ways:

• Manual: the user types $ in chat and selects a skill from the popover.
• Model-invoked: the model chooses a skill from the injected skill catalog and calls the skill tool.
• Always apply: the skill is primed into every turn when active.

What actually enters the context differs by path:

• The model-invoked catalog carries only names and descriptions, up to 100 skills, with each entry trimmed to roughly 250 characters. Instruction bodies are not part of the catalog.
• Manual and always-apply invocation prime the full SKILL.md body for that turn, up to 10 manual and 20 always-apply skills, and 30 combined. When the combined cap is exceeded, always-apply skills are dropped first so explicit user intent survives.

Manual invocation is explicit user intent. It can use skills that are hidden from model invocation with disable-model-invocation: true, as long as user-invocable is not false.

Agent Scope

Agents must have Enable skills turned on before they can use or author Skills. The separate Use all skills switch controls catalog exposure.

• All: turn on Use all skills to expose the full active catalog visible to the user, including Skills added later.
• Selected: leave Use all skills off and add individual Skills to expose only those entries.
• Authoring only: leave Use all skills off with no selected Skills. Existing catalog entries are not exposed, but the agent can create a Skill during a conversation when the user has Skill create permission.
• Disabled: turn off Enable skills to disable both catalog use and runtime authoring.

This lets admins expose the Skills feature globally while keeping each agent's usable skill set focused.

Turning Use all skills off restores the selection that was active before the switch was enabled. Existing agents retain the legacy behavior where Skills enabled with no explicit scope means the full catalog.

Runtime Skill Authoring

An agent with Skills enabled can create or edit reusable Skill files while it works. Runtime files use the same skills/{skillName}/... namespace as uploaded bundles, so the agent can author SKILL.md and supporting references, scripts, or assets as part of a successful workflow.

Authoring follows the normal Skills permission model:

• Creating a new Skill requires the user's Skill Create permission.
• Editing an existing Skill requires both edit access and inclusion in the agent's active catalog scope; deployment and GitHub-synced Skills remain read-only.
• An authoring-only agent can create a new Skill without receiving the user's existing catalog.

Runtime authoring does not bypass the deployment capability or user permissions. Removing skills from the Agents endpoint capabilities hides the feature, and turning Enable skills off on the agent disables its authoring tools.

Active and Shared Skills

Users can toggle skills active or inactive with the Available to agent switch. Owned and deployment skills default to active. Shared skills use the admin-configured default until the user overrides them.

Inactive skills are excluded from:

• The $ popover
• The model-invoked skill catalog
• Always-apply priming

Sharing a skill grants viewer, editor, or owner access to specific users, groups, or roles through the standard share dialog, and requires the share permission on your role. See Access Control for the full model.

Bundled Files

Uploaded skill bundles can include files alongside SKILL.md, such as:

• references/...
• scripts/...
• assets/...

The backend stores those files with the skill. The agent can resolve skill files when the skill is active and in scope. Nested files keep their relative paths and are addressed through the model-facing skills/{skillName}/... namespace. In the Skill viewer, relative Markdown links resolve from the current file and open the referenced file within the same Skill. When Code Interpreter is enabled, the same files are mounted at /mnt/data/skills/{skillName}/... so shell and code operations can use them directly. Editing SKILL.md advances the Skill version; before code or programmatic execution, LibreChat verifies every mounted file reference matches that version and re-uploads the complete bundle when any reference is stale.

A skill's page also has a file tree with New File, New Folder, and Upload File actions, at up to 10 MB per added file. SKILL.md itself is reserved there: edit the skill body instead.

Deployment Skills

Admins can ship read-only Skills from the filesystem with DEPLOYMENT_SKILLS_DIR.

DEPLOYMENT_SKILLS_DIR=./skill

The directory defaults to ./skill at the project root. Each skill lives in its own subdirectory containing a SKILL.md, with any bundled files beside it. LibreChat loads deployment Skills at startup and exposes them to users with the Skills capability enabled.

Deployment Skills:

• Are read-only in the UI
• Use deployment as their source
• Take precedence over persisted Skills with the same name
• Require a LibreChat restart after files are added, removed, or changed

Experimental Agent Plugins can also bundle read-only deployment Skills together with related MCP servers. A Skill in the standalone deployment directory takes precedence over a plugin Skill with the same name.

GitHub Skill Sync

Admins can mirror Skills from GitHub repositories with skillSync.github in librechat.yaml. This is the practical way to share a curated set of skills across a team.

skillSync:
  github:
    enabled: true
    intervalMinutes: 60
    runOnStartup: true
    sources:
      - id: librechat-skills
        owner: your-org
        repo: your-skills-repo
        ref: main
        paths:
          - skills
        skillDiscoveryDepth: 2
        token: '${GITHUB_SKILLS_TOKEN}'

GitHub Skill Sync:

• Scans configured repository paths for SKILL.md
• Treats the directory containing each SKILL.md as a skill root, within skillDiscoveryDepth levels of the configured path
• Imports bundled files beside each skill
• Stores mirrored Skills with source: "github"
• Updates mirrored Skills when the upstream repository changes
• Removes mirrored Skills that no longer exist in the configured source
• Publishes valid Skills even when another Skill in the source is invalid or conflicts
• Reports partially successful runs and bounded skipped-Skill details to administrators
• Supports scheduled, startup, and manual admin-triggered runs

A skipped Skill keeps its last-known-good mirror when one exists. Source-wide failures such as authentication, rate limiting, lost sync ownership, or an unsuccessful rollback still fail the complete source run.

Use a GitHub fine-grained personal access token with read-only Contents and Metadata permissions for the selected repository. See Skill Sync Object Structure for all fields, credential options, tenant scoping, and admin sync endpoints.