Skill Sync Object Structure

Overview

The skillSync object lets admins mirror Skills from external sources. In v1.3.13, 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

Credentials

Use either token or credentialKey for each source, not both. token must be an environment variable reference such as ${GITHUB_SKILLS_TOKEN}. Use a GitHub fine-grained personal access token scoped to the selected repository with read-only Contents and Metadata permissions.

Top-Level Fields

skillSync.github

Key	Type	Description	Example
github.enabled	Boolean	Enables or disables GitHub Skill Sync.	enabled: true
github.intervalMinutes	Number	How often scheduled GitHub Skill Sync runs. Must be between 5 and 35791 minutes.	intervalMinutes: 60
github.runOnStartup	Boolean	Runs GitHub Skill Sync when the server starts.	runOnStartup: true
github.sources	Array of Objects	GitHub repositories and paths to scan for Skills. Required when GitHub Skill Sync is enabled.

Defaults:

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

Source Fields

Each github.sources entry configures one repository source.

Key	Type	Description	Example
id	String	Stable unique source id. Must start with a letter or digit and contain only letters, digits, underscores, or hyphens.	id: librechat-skills
owner	String	GitHub organization or user name.	owner: your-org
repo	String	GitHub repository name.	repo: your-skills-repo
ref	String	Git ref, branch, tag, or commit to read. Defaults to `main`.	ref: main
paths	Array of Strings	Repository paths to scan. Use `.` to scan from the repository root.	paths: ["skills"]
skillDiscoveryDepth	Number	Directory depth below each configured path to scan for `SKILL.md`. Defaults to `2`; maximum is `10`.	skillDiscoveryDepth: 2
token	String	Environment variable reference containing a GitHub token. Mutually exclusive with `credentialKey`.	token: '${GITHUB_SKILLS_TOKEN}'
credentialKey	String	Stored GitHub credential key managed through the admin Skill Sync credential endpoints. Mutually exclusive with `token`.	credentialKey: production-skills
tenantId	String	Optional tenant id that owns mirrored Skills when tenant isolation is enabled.	tenantId: tenant-a

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.
Uses a sync lock so only one GitHub sync run proceeds at a time.

Admin Endpoints

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

Key	Type	Description
GET /api/admin/skills/sync/status	Endpoint	Returns enabled state, schedule settings, source status, credential presence, and recent sync counts.
POST /api/admin/skills/sync/run	Endpoint	Starts a manual sync run when the caller has the required admin Skills capability.
PUT /api/admin/skills/sync/credentials/:credentialKey	Endpoint	Stores or rotates a GitHub token for a credential key.
DELETE /api/admin/skills/sync/credentials/:credentialKey	Endpoint	Deletes a stored GitHub token for a credential key.

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