---
title: "GitHub Sync"
description: "Mirror your organization's skills to a GitHub repository: folder-structured, versioned, and continuously synced."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.localskills.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Sync

GitHub Sync mirrors your organization's entire skill library, folder structure
included, to a GitHub repository. Skills stay reviewable, diffable, and
greppable in the tooling your team already uses.

## How it works

Sync is **bidirectional**. Skill and folder changes made on the platform push
to the repo automatically in the background. Pushes to the connected branch
flow the other way: edits to `SKILL.md`, `RULE.md`, or package files import
back as new skill versions, and a brand-new directory containing a `SKILL.md`
creates a new private skill. Imported versions record their provenance (commit
and author) in the version message and audit log.

Deleting or moving a skill directory in the repo does **not** delete or move
the skill; the next full sync restores it. When the same skill changes in both
places between syncs, **GitHub wins**: both edits are kept in the version
history, and the repo's content becomes the current version, even if the
platform edit was saved after the push. After an import, the sync bot pushes
one small commit refreshing each skill's `.localskills.json` version metadata.

**Sync now** first imports any pending repo changes, then runs a full
re-mirror. It is also the recovery path if a webhook delivery was missed.

## Connecting a repository

From **Organization > GitHub Sync**, click **Connect GitHub repo**. You'll be
sent through a GitHub App installation where you pick the account and
repository; back on the settings page you confirm the repo and the first full
sync runs.

Connecting, disconnecting, and manual syncs require the `GitHub sync: manage`
permission and are recorded in the audit log (`github_sync.connect`,
`github_sync.disconnect`, `github_sync.manual_sync`).

## Repository layout

Each skill becomes a directory under `skills/` following your organization's
folder tree, and an auto-generated `skills/README.md` indexes every skill.
Everything outside `skills/` (your own README, `.github/`, workflows, docs) is
never written to or deleted:

```text
skills/
  README.md                        # auto-generated skill index
  engineering/
reviews/
  code-review-checklist/
    .localskills.json          # id, version, semver, type, visibility, tags, authors
    SKILL.md                   # text skill content (managed header)
    references/security.md     # package skills: every file, verbatim
    scripts/diff-stats.sh
  marketing/
landing-page-copy/
  .localskills.json
  RULE.md                      # rules use RULE.md instead of SKILL.md
```

Text skills are written as a single `SKILL.md` (or `RULE.md` for rules) with a
managed header noting that edits sync back. Package skills are unpacked in
full: every file in the package appears in the repo. The `.localskills.json`
sidecar records the skill id, current version and semver, type, visibility,
tags, and author attribution: `author` is the skill's creator and
`versionAuthor` is whoever published the mirrored version (each a
`{ name, username }` object, or `null` for anonymous authors). The README
index also lists each skill's author. These fields are informational:
repo-side edits to them never sync back, and versions imported from repo
pushes are attributed to the member who connected the repo, with the GitHub
commit author preserved in the version message.

Renaming or moving a folder on the platform renames the corresponding paths in
the repo on the next sync.

## Security considerations

> **Note**
>
> **All** skills are mirrored, including private and unlisted ones and skills
> in [restricted folders](/folders). "Private" in the repo means readable by
> every current and future repo collaborator and GitHub org member, a set
> localskills.sh does not control. With bidirectional sync this cuts both
> ways: **repo write access is write access to every synced skill**, including
> those in restricted folders; repo pushes bypass folder access controls. Use
> a private repository, protect the connected branch if you want review before
> import, and manage repo access as carefully as you manage organization
> membership.

Disconnecting removes the platform's access: the GitHub App installation is
uninstalled once no other organization still uses it. The mirrored files
remain in your repo.

Source: https://docs.localskills.sh/github-sync/index.mdx