# Skills Sync CLI > 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. - Skill: `mono0926/skills-sync-cli` (Agent Skill) - Install (CLI): `npx skillmds@latest add mono0926/skills-sync-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/mono0926/skills-sync-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mono0926 (https://skillmd.com/u/mono0926) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mono0926/skills-sync-cli --- # 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 `: 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 `: 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`. - `` (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.