sync-skills

自建 Skill 的全生命周期管理器。

它不是一个“下载别人 Skill 的工具”，也不是一个 Skill 商店。
它解决的是另一类问题：你自己写出来的 Skill，怎么持续迭代、怎么给多个本地 Agent 使用、怎么放到 GitHub 做备份与分享、怎么在多台电脑之间同步。

一句话定位

sync-skills 是一个 author-first、Git-first、repo-first 的 Skill 管理工具。

• author-first：先服务“我自己写 Skill、我自己维护 Skill”这件事
• Git-first：版本管理、备份、协作、跨设备同步都建立在 Git 之上
• repo-first：当前分发粒度是“整个个人 Skill 仓库”，不是单个 Skill 包

它打通了什么

一条完整主线：

1. 创建一个新 Skill
2. 在本地持续修改和迭代
3. 让多个 Agent 同时可见
4. 把整个 Skill 仓库推到 GitHub
5. 在另一台电脑上继续拉取和使用
6. 在不再需要时解绑、删除或下线

核心能力

• 创建与纳管：创建新 Skill，或把已有 Skill 纳入统一管理
• 本地分发：通过符号链接把同一个 Skill 暴露给多个 Agent
• 版本管理：基于 Git 做提交、推送、拉取和回滚，并在失败时给出明确提示后安全退出
• 多机同步：通过远程仓库在多台设备之间保持一致
• 生命周期管理：支持 link、unlink、remove、doctor、status 等日常操作
• Agent 接管：skill-manager 是个人 Skill 仓库 ~/Code/Skills/skills/skill-manager/ 中的统一总入口，并将确定性的生命周期操作委托给本项目提供的 sync-skills CLI

工作模型

当前模型很明确：

• 你维护一个自己的 Skill 仓库
• 仓库里的 Skill 是事实源
• 各个 Agent 目录通过 symlink 使用这些 Skill
• GitHub 远程仓库用于备份、分享和跨设备同步

这意味着当前主线不是：

• 搜索别人发布的 Skill
• 像包管理器一样安装单个第三方 Skill
• 维护一个中心化 Skill registry

这些不是当前产品主线。

最小使用流程

sync-skills init
sync-skills new my-skill --from-dir /tmp/my-skill --dry-run
sync-skills commit --skill my-skill --dry-run --json
sync-skills push --skill my-skill --dry-run --json

如果你换了一台电脑，主线通常是：

sync-skills init
sync-skills pull

当前命令

内置 Agent 帮助

CLI 自带的帮助是当前命令契约，可直接供人或 Agent 查询：

sync-skills --help
sync-skills <command> --help

顶层帮助包含生命周期路由、只读与写入边界、frontmatter 规则和推荐事务流程；每个子命令进一步说明适用场景、实际副作用、参数含义、哈希冻结方式和可复制示例。Agent 应优先读取目标子命令帮助，不需要从旧文档推测命令行为。

Git 行为

• commit / push 可按 --skill / --path 冻结精确写入范围，排除其他工作区改动，并用 expected-change-hash 阻止预览后的漂移
• 生命周期自动提交只包含本次操作涉及的 Skill；批量删除只提交和验收一次
• link -y 不会按修改时间替用户决定不同内容的权威版本
• commit 在无改动时会直接跳过，不创建空提交
• push 会先预览将要执行的 Git 命令；首次推送会建立 origin/<branch> 追踪
• push 在本地落后远程或与远程已分叉时，会明确提示先执行 sync-skills pull
• pull 会先预览实际的 git pull --rebase 命令；成功后在同一次命令中对齐状态并修复本地链接
• commit / push / pull 在 git 不可用、未配置远程、认证失败、detached HEAD、本地未提交改动、冲突或远程分支缺失等场景下，都会给出明确提示并安全退出

为什么现在不需要 publish / import / install-from-git

因为当前分发模型已经足够清晰：

• init：建立本地管理基线
• push：把整个仓库放到远程
• pull：在别的设备继续使用同一个仓库

只有当产品将来要支持“单个 Skill 的独立发布、独立安装、独立引用”时，publish / import / install-from-git 才会变成必要能力。
在当前的 repo-first 模型下，它们不是主线需求。

文档

• 设计文档：docs/DESIGN.md
• 用户故事：docs/USER_STORIES.md
• 变更历史：CHANGELOG.md
• Agent Skill 定义：~/Code/Skills/skills/skill-manager/SKILL.md

sync-skills

The lifecycle manager for self-authored Skills.

This is not a tool for downloading other people's Skills, and it is not a Skill marketplace.
It solves a different problem: once you create your own Skill, how do you iterate on it, expose it to multiple local agents, back it up or share it through GitHub, and keep it synced across multiple machines?

Positioning

sync-skills is an author-first, Git-first, repo-first Skill manager.

• author-first: built for people who create and maintain their own Skills
• Git-first: versioning, backup, collaboration, and multi-device sync are all based on Git
• repo-first: the current distribution unit is the whole personal Skill repository, not an individual Skill package

What it covers

One complete path:

1. Create a new Skill
2. Keep iterating on it locally
3. Make it visible to multiple agents
4. Push the whole Skill repository to GitHub
5. Pull and continue using it on another machine
6. Unlink, remove, or retire it when it is no longer needed

Core capabilities

• Creation and adoption: create a new Skill or bring an existing one under management
• Local distribution: expose the same Skill to multiple agents through symlinks
• Version management: use Git for commit, push, pull, and history-based recovery, with explicit failure hints and safe exits
• Multi-device sync: keep the repository aligned across machines through a remote
• Lifecycle operations: manage daily operations through link, unlink, remove, doctor, and status
• Agent handoff: skill-manager at ~/Code/Skills/skills/skill-manager/ is the orchestration entry point and delegates deterministic lifecycle operations to this project's sync-skills CLI

Operating model

The current model is explicit:

• You maintain one personal Skill repository
• Skills inside that repository are the source of truth
• Agent directories consume those Skills through symlinks
• The GitHub remote is used for backup, sharing, and multi-device sync

This means the current product is not centered on:

• discovering Skills published by others
• installing a single third-party Skill like a package manager
• maintaining a centralized Skill registry

Those are not the mainline product goals today.

Minimal workflow

sync-skills init
sync-skills new my-skill --from-dir /tmp/my-skill --dry-run
sync-skills commit --skill my-skill --dry-run --json
sync-skills push --skill my-skill --dry-run --json

On another machine, the mainline usually looks like:

sync-skills init
sync-skills pull

Current commands

Built-in Agent help

The CLI help is the current executable command contract for humans and Agents:

sync-skills --help
sync-skills <command> --help

Top-level help covers lifecycle routing, read/write boundaries, frontmatter rules, and recommended transaction flows. Every subcommand then documents when to use it, its actual effects, argument semantics, hash-freezing workflow, and copyable examples. Agents should inspect the target command help instead of inferring behavior from older documentation.

Git behavior

• commit / push can freeze exact --skill / --path scopes, exclude unrelated worktree changes, and reject drift through expected-change-hash
• Lifecycle auto-commits include only affected Skill paths, and batch removal commits and verifies once
• link -y never chooses between divergent contents by modification time
• commit skips clean worktrees instead of creating empty commits
• push previews the exact Git commands first; the first push establishes origin/<branch> tracking
• push explicitly tells you to run sync-skills pull when the local branch is behind the remote or has diverged
• pull previews the exact git pull --rebase command first, then reconciles state and restores local link visibility in the same command
• commit, push, and pull fail safely with explicit hints for missing git, missing remote, auth failure, detached HEAD, local uncommitted changes, conflicts, and missing remote branches

Why publish / import / install-from-git are not required yet

Because the current distribution model is already coherent:

• init: establish local management
• push: send the whole repository to a remote
• pull: continue using the same repository on another device

publish, import, and install-from-git only become necessary if the product later moves to independent publishing, installation, or referencing at the single-Skill level.
Under the current repo-first model, they are not mainline requirements.

Documents

• Design: docs/DESIGN.md
• User stories: docs/USER_STORIES.md
• Changelog: CHANGELOG.md
• Agent skill definition: ~/Code/Skills/skills/skill-manager/SKILL.md