# Skill Sync Object Structure (https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/skill_sync)

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

```yaml filename="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}'
        # credentialKey: production-skills
        # tenantId: your-tenant-id
```

<Callout type="warning" title="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.
</Callout>

## Top-Level Fields

### skillSync.github

<OptionTable
  options={[
    ['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.

<OptionTable
  options={[
    [
      '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:

<OptionTable
  options={[
    [
      '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.