Back to Details

skills-sync

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skills Sync

Skills Sync

A skill for using the 
skills_sync
CLI tool, which is used to manage and sync AI agent skills.
用于使用
skills_sync
CLI工具的技能，该工具可管理和同步AI agent技能。

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.
skills_sync
工具会读取配置文件，将用户的本地技能目录（通常为
~/.agents/skills
）与远程仓库同步。
配置优先级：
  1. 项目专属：
    ./skills.yaml
  2. 全局：
    ~/.config/skills_sync/skills.yaml
重要提示：当其他技能（例如
skills-optimizer
）修改
skills.yaml
配置时，这些变更不会自动生效。你必须运行
skills_sync sync
来下载新技能、移除已删除的技能并应用排除规则。

Commands

命令

Here are the primary commands for 
skills_sync
:
以下是
skills_sync
的核心命令：

skills_sync sync

skills_sync sync

Synchronizes the skills based on the configuration file.
  • When to use: Immediately after any modifications to 
    ~/.config/skills_sync/skills.yaml
    or when the user requests to update their skills.
  • Action: It fetches repositories, applies includes/excludes, and ensures locally installed skills match the configuration.
根据配置文件同步技能。
  • 适用场景：在修改
    ~/.config/skills_sync/skills.yaml
    后立即执行，或当用户请求更新其技能时执行。
  • 执行动作：拉取仓库、应用包含/排除规则，确保本地安装的技能与配置一致。

skills_sync list

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

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.
在用户默认编辑器（或
$EDITOR
环境变量指定的编辑器）中打开
skills.yaml
配置文件。
  • 适用场景：当用户想要手动编辑配置而非由AI完成编辑时使用。

skills_sync init

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.
如果默认全局配置文件（
~/.config/skills_sync/skills.yaml
）不存在，则生成该文件。
  • 适用场景：通常仅在首次设置时需要，用于补全缺失的配置文件。

skills.yaml
Specification

skills.yaml
规范

The 
skills.yaml
file defines which skills are installed and where.
skills.yaml
文件定义了要安装的技能及其安装位置。

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.
  • global
    ：此处列出的技能会被全局安装到
    ~/.agents/skills
    。
  • <路径>
    （例如
    ~/Git/my-project
    ）：此处列出的技能会被安装到指定项目目录下的
    .agents/skills
    中。如果引用的路径在用户文件系统中不存在，
    skills_sync
    会跳过该路径且不会报错。

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.
在每个目标目录下，你需要定义拉取技能的来源：
  • owner/repo
    ：GitHub仓库的简写形式。
  • https://github.com/owner/repo/tree/branch
    ：仓库中的特定分支或文件夹。
  • /local/path/to/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.
对于每个来源，你可以指定过滤器列表来决定要安装的技能：
  • 空/Null：如果未提供过滤器（仅为空键），则安装来源中的所有技能。
  • 指定名称：提供技能的精确名称（例如
    flutter-expert
    ）。
  • 通配符（
    *
    ）    ：使用通配符匹配多个技能（例如
    flutter-*
    会安装所有以
    flutter-
    开头的技能）。
  • 排除规则（
    !
    ）    ：在模式前添加
    !
    前缀以排除匹配的技能（例如
    !*-legacy
    会跳过所有以
    -legacy
    结尾的技能）。排除规则优先级高于包含规则。

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

工作流集成（例如与
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.
如果你要修改用户的
skills.yaml
（例如添加或移除技能）：
  1. 识别配置文件：检查是否存在项目本地的
    skills.yaml
    ，如果不存在，则使用全局的
    ~/.config/skills_sync/skills.yaml
    。
  2. 修改配置：根据用户指令或你的优化逻辑编辑识别到的
    skills.yaml
    文件。
  3. 应用变更：通过命令行执行
    skills_sync sync
    以确保变更生效。
  4. 校验：可选步骤，运行
    skills_sync list
    确认安装结果符合预期。

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 are not currently supported: If you change the yaml and run sync, it will make destructive changes (deleting unlisted skills). Be sure of the user's intent before syncing after a configuration removal.
  • 不要自动执行
    sync
    命令    ：切勿在未获得用户明确许可的情况下运行
    skills_sync sync
    。修改配置后，务必询问用户是否要应用变更。
  • 配置修改透明化：不要静默修改
    skills.yaml
    。要清晰解释你正在添加或移除的技能及其原因，确保用户始终完全了解其已安装的技能情况。
  • 不要猜测文件路径：始终依赖
    skills_sync
    工具处理安装逻辑、克隆和复制操作。除非明确要求绕过该工具，否则不要尝试手动下载zip文件或使用
    git
    将仓库克隆到
    ~/.agents/skills
    。
  • 等待执行完成：如果需要下载大型仓库，
    skills_sync sync
    可能需要一定时间，请等待命令执行完毕。
  • 当前不支持试运行：如果你修改了yaml文件并运行sync命令，会执行破坏性变更（删除未列出的技能）。在移除配置后执行同步前，请务必确认用户的意图。