---
name: skills_sync-cli
description: Provides usage instructions and best practices for the skills_sync CLI tool. Use this to understand how to manage, sync, and configure AI agent skills based on the user's config file.
---

# Skills Sync

A skill for using the `skills_sync` CLI tool, which is used to manage and sync AI agent skills.

## Context

The `skills_sync` tool reads a configuration file and synchronizes the user's local skills directory (typically `~/.agents/skills`) with remote repositories.

**Configuration Precedence**:

1. Project-specific: `./skills.yaml`
2. Global: `~/.config/skills_sync/skills.yaml`

**Crucial Note**: When another skill (like `skills-optimizer`) modifies the `skills.yaml` configuration, those changes are NOT automatically applied. You MUST run `skills_sync sync` to download new skills, remove deleted ones, and apply exclusions.

## Commands

Here are the primary commands for `skills_sync`:

### `skills_sync sync`

Synchronizes the skills based on the configuration file. By default, it performs a "clean" sync by removing existing skills first.

- **When to use**: Immediately after any modifications to `~/.config/skills_sync/skills.yaml` or when the user requests to thoroughly ensure their skills directory matches the config.
- **Options**:
  - `--clean`: (Default: `true`) Deletes existing skills before installation.
  - `--no-clean`: Skips deletion. Faster, but might leave orphaned skills.
  - `--agent <name>`: Target a specific agent (default: `antigravity`). Use `*` for all.
- **Action**: It fetches repositories, applies includes/excludes, and ensures locally installed skills match the configuration.

### `skills_sync update`

Checks for and installs the latest versions of already configured skills without deleting anything first.

- **When to use**: When you want a quick check for skill updates without the overhead of a full sync.
- **Options**:
  - `--agent <name>`: Target a specific agent (default: `antigravity`).
- **Action**: Runs `npx skills update` across all configured target paths.

### `skills_sync list`

Lists the current configuration and locally installed skills.

- **When to use**: To verify what is currently configured vs. what is actually installed, or to show the user their current setup.

### `skills_sync config`

Opens the `skills.yaml` configuration file in the user's default editor (or the editor specified by `$EDITOR`).

- **When to use**: When the user wants to manually edit their configuration rather than having the AI do it.

### `skills_sync init`

Generates the default global configuration file (`~/.config/skills_sync/skills.yaml`) if it does not exist.

- **When to use**: Usually only necessary for first-time setup if the file is missing.

## `skills.yaml` Specification

The `skills.yaml` file defines which skills are installed and where.

### Target Directories (Root Keys)

- `global`: Skills listed here are installed globally to `~/.agents/skills`.
- `<path>` (e.g., `~/Git/my-project`): Skills listed here are installed locally to `.agents/skills` within the specified project directory. If the referenced path does not exist on the user's filesystem, `skills_sync` will skip it without error.

### Skill Sources

Under each target directory, you define the sources to fetch skills from:

- `owner/repo`: A shorthand for a GitHub repository.
- `https://github.com/owner/repo/tree/branch`: A specific branch or folder in a repository.
- `/local/path/to/skills`: A local directory containing skills.

### Skill Selection (Filters)

For each source, you can specify a list of filters to determine which skills to install:

- **Empty / Null**: If no filters are provided (just an empty key), all skills from the source are installed.
- **Specific Names**: Provide the exact name of the skill (e.g., `flutter-expert`).
- **Wildcards (`*`)**: Use wildcards to match multiple skills (e.g., `flutter-*` installs all skills starting with `flutter-`).
- **Exclusions (`!`)**: Prefix a pattern with `!` to exclude matching skills (e.g., `!*-legacy` skips skills ending in `-legacy`). Exclusions take precedence over inclusions.

## Workflow Integration (e.g., with `skills-optimizer`)

If you are modifying the user's `skills.yaml` (e.g., adding or removing skills):

1. **Identify the config file**: Check if a project-local `skills.yaml` exists. If not, use the global `~/.config/skills_sync/skills.yaml`.
2. **Modify the configuration**: Edit the identified `skills.yaml` file according to the user's instructions or your optimization logic.
3. **Apply the changes**: Execute `skills_sync sync` via the command line to ensure the changes take effect.
4. **Verify**: Optionally, run `skills_sync list` to confirm the installation matches expectations.

## Best Practices

- **Do not execute `sync` automatically**: NEVER run `skills_sync sync` without explicit user permission. Always ask the user if they want to apply the changes after you have modified the configuration.
- **Transparency in Configuration**: Do not modify `skills.yaml` silently. Clearly explain which skills you are adding or removing and why, ensuring the user maintains full awareness of their installed skills at all times.
- **Do not guess file paths**: Always rely on the `skills_sync` tool to handle the installation logic, cloning, and copying. Don't try to manually download zip files or clone repos with `git` to `~/.agents/skills` unless specifically requested to bypass the tool.
- **Wait for completion**: `skills_sync sync` might take a moment if it needs to download large repositories. Allow the command to finish.
- **Dry runs**: You can use `--dry-run` to see what commands `skills_sync` would execute without actually performing them.