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

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 also control who can use, create, share, and publicly share skills.

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. 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.

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
• 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.

Create a Skill

Open Skills from the side panel. You can write a skill directly in LibreChat or upload a .md, .zip, or .skill file that contains SKILL.md.

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

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.

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.

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. 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

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.