Skill Sync Object Structure

Overview

The skillSync object lets admins mirror Skills from external sources. GitHub is the supported provider.

GitHub Skill Sync reads SKILL.md files and their bundled files from configured repository paths, stores them as Skills with source: "github", and keeps mirrored rows aligned with the upstream repository on later syncs.

Example

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}'
        # credentialKey: production-skills
        # tenantId: your-tenant-id

Top-Level Fields

skillSync.github

Defaults:

• enabled: false
• intervalMinutes: 60
• runOnStartup: false
• sources: []

Source Fields

Each github.sources entry configures one repository source.

Source Identity

The id field is part of the mirror identity. Keep it stable. Repointing a source to a renamed repository or a new ref keeps mirrored Skills linked to the same source id, while changing the source id creates a new mirror.

When tenantId is set, sync reads and writes run inside that tenant's isolation context. Treat tenantId as immutable for a source id: changing, adding, or removing it later leaves previously mirrored Skills in the old tenant.

Sync Behavior

GitHub Skill Sync:

• Discovers SKILL.md files below each configured path.
• Imports the SKILL.md body, frontmatter, and bundled files.
• Stores source metadata such as source id, owner, repo, ref, skill path, commit SHA, and blob SHA.
• Updates mirrored Skills when the upstream file changes.
• Deletes mirrored Skills and files that were removed from the configured source.
• Validates and publishes Skills independently, so one invalid or conflicting Skill does not hide valid Skills from the same source.
• Preserves a skipped Skill's last-known-good mirror and rolls back incomplete writes for that Skill.
• Marks a run partial when it publishes at least one Skill but skips another, and records a bounded skipped count and details for administrator status reads.
• Uses a sync lock so only one GitHub sync run proceeds at a time.

Unknown SKILL.md frontmatter keys are accepted when their values remain within the bounded, JSON-safe extension limits. Invalid recognized fields, unsafe extension values, duplicate names, and ownership conflicts skip only the affected Skill. Authentication, rate-limit, lock-loss, repository access, and rollback failures remain source-level failures.

Admin Endpoints

The admin API exposes GitHub Skill Sync status, manual runs, and stored credential management:

Status reads require admin access and Skills read permission. Manual runs and credential writes require platform-level Skills management permission.

Skill Deletion

The top-level skillDeletion object controls the background process that finishes deleting Skills and cleans up their stored files, along with abandoned Skill uploads. It is separate from skillSync and applies to all Skills. Unknown keys are rejected.

skillDeletion:
  finalizationEnabled: true
  sweepIntervalMs: 60000
  claimLeaseMs: 120000
  batchSize: 100
  recheckIntervalMs: 3600000

Deployment Skills from Disk

Separate from skillSync, LibreChat loads Skills from a directory on the server at startup. Each skill is a folder with a SKILL.md and any bundled files. The directory is ./skill at the project root unless you set DEPLOYMENT_SKILLS_DIR in .env (see dotenv).

Deployment Skills are shown to every user who has the Skills capability, are read-only in the UI, and hide any user-created skill with the same name. They are read once at startup, so restart LibreChat after adding, removing, or editing files. Agent Plugins can also ship deployment Skills; a Skill in this directory wins over a plugin Skill with the same name.