# Skill Sync

> Manage local skills backed by known remote Git repositories. Use when the user wants to import, inspect, diff, pull, resolve, push, reset, or remove them, or project current local skills to enabled clients with `al sync`. Do not use to discover new skills or create user-owned skills.

- Skill: `conn-castle/skill-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add conn-castle/skill-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/conn-castle/skill-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: conn-castle (https://skillmd.com/u/conn-castle)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/conn-castle/skill-sync

---


<!-- agent-layer-catalog-skill: skill-sync -->

# Skill Sync

Use this skill to import known skills from Git and manage them over time. Users
can edit imported skills locally, pull upstream updates without overwriting
those edits, pin imports to a chosen version, reset them to upstream, or publish
changes back.

Use live `al skills --help` and subcommand help as the source of truth. If `al`
is unavailable or the project is not initialized, stop and report the error.
Do not replace an `al skills` operation with manual file edits.

There is no `al skills sync` command. Use `al skills pull` to update skills from
Git. Use `al sync` only to copy the current local skills into enabled client
directories.

1. Start with `al skills status --all`. It reads local state without using the
   network. A `conflicted` skill includes its Git workspace path.
2. To compare live trees, run `al skills diff <name>` with `--from`/`--to`
   `base`, `local`, `upstream`, or `destination`. Defaults are local to
   upstream. The output is an ordinary Git unified diff.
3. To import skills, run `al skills add <repository> <selector>... --yes` only
   when the user explicitly requests the import and the repository and
   selectors are known. Quote selectors that contain wildcards or start with
   `!`. The command does not search for, recommend, or preview skills. Run `al
   skills add --help` before choosing source, tracking, or publishing options.
4. To update imported skills, run `al skills pull`. It fetches every configured
   source and merges upstream changes with local edits. Pinned imports stay at
   their locked versions unless their configured `ref` changes. Treat any
   partial or conflicted result as a failure and report every result. For a
   conflict, finish the Git merge in the workspace named in the error, `git add`
   the result, then run `al skills resolve <name>`. Do not hand-edit the
   lockfile.
5. To stop managing one selector, run `al skills remove <repository>
   <selector> --yes` only when the user explicitly requests the removal, using
   the exact values from `.agent-layer/config.toml`. Skills still matched by
   another selector remain managed. Clean skills that are no longer matched
   are deleted. If one has local edits, the command fails and preserves it.
   Removing an exclusion may import newly included skills.

Edit an imported skill only in `.agent-layer/skills-imported/<skill-name>/`. Do
not edit the generated copies under `.agents/skills/` or `.claude/skills/`. The
`al sync` command replaces them.

## Discarding local edits

Run `al skills reset <name> --yes` only when the user explicitly asks to discard
that skill's local edits. It permanently replaces exactly one skill with the
current upstream version selected by its import configuration, even when the
import is pinned. It creates no backup. Use the exact skill name shown by
`al skills status --all`.

## Publishing changes

`al skills push --yes` can publish changes from every writable import in one
run. Run it only when the user explicitly asks to publish local changes. Before
running it, confirm in `.agent-layer/config.toml` that every writable
destination matches the user's request. If one does not match, stop and ask.
Do not change write settings silently.

Push uses only configured destinations and branches. It never pulls first,
force-pushes, or opens a pull request. A destination merge conflict leaves the
same kind of Git workspace as pull; finish it with `al skills resolve <name>`
and rerun push. If it fails, report each failed skill and the required action.

Use existing Git authentication. Repository URLs must not contain literal
credentials. Use `${AL_*}` placeholders whose values are stored in
`.agent-layer/.env`.