skills-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

Project-specific:
```
./skills.yaml
```
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

）与远程仓库同步。

配置优先级：

项目专属：
```
./skills.yaml
```
全局：
```
~/.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):

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

如果你要修改用户的

skills.yaml

（例如添加或移除技能）：

识别配置文件：检查是否存在项目本地的
```
skills.yaml
```
，如果不存在，则使用全局的
```
~/.config/skills_sync/skills.yaml
```
。
修改配置：根据用户指令或你的优化逻辑编辑识别到的
```
skills.yaml
```
文件。
应用变更：通过命令行执行
```
skills_sync sync
```
以确保变更生效。
校验：可选步骤，运行
```
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命令，会执行破坏性变更（删除未列出的技能）。在移除配置后执行同步前，请务必确认用户的意图。

skills-sync

Original

Translation

Skills Sync

Skills Sync

Context

上下文

Commands

命令

`skills_sync sync`

`skills_sync sync`

`skills_sync list`

`skills_sync list`

`skills_sync config`

`skills_sync config`

`skills_sync init`

`skills_sync init`

`skills.yaml`
Specification

`skills.yaml`
规范

Target Directories (Root Keys)

目标目录（根键）

Skill Sources

技能来源

Skill Selection (Filters)

技能选择（过滤器）

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

工作流集成（例如与
`skills-optimizer`
集成）

Best Practices

最佳实践

skills-sync

Original

Translation

Skills Sync

Skills Sync

Context

上下文

Commands

命令

skills_sync sync

skills_sync sync

skills_sync list

skills_sync list

skills_sync config

skills_sync config

skills_sync init

skills_sync init

skills.yaml Specification

skills.yaml 规范

Target Directories (Root Keys)

目标目录（根键）

Skill Sources

技能来源

Skill Selection (Filters)

技能选择（过滤器）

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

工作流集成（例如与skills-optimizer集成）

Best Practices

最佳实践

`skills_sync sync`

`skills_sync sync`

`skills_sync list`

`skills_sync list`

`skills_sync config`

`skills_sync config`

`skills_sync init`

`skills_sync init`

`skills.yaml`
Specification

`skills.yaml`
规范

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

工作流集成（例如与
`skills-optimizer`
集成）