Skip to content

feat(skills): 引入 skills-lock.json 统一同步机制 #137

@Besthope-Official

Description

@Besthope-Official

name: Feature Request
about: Propose a new feature or enhancement

Use Case

当前仓库有两类 skill 来源:

  • 本仓库自研 skill(放在 .claude/skills
  • 通过 npx skills 从外部 repo 引入的 skill(跨 repo 复用)

现状:自研 skill 目录结构(<name>/SKILL.md + YAML frontmatter)已与 vercel-labs/skills 框架兼容,可直接被 npx skills add 安装。但外部 skill 的来源和版本快照无法被稳定记录,团队成员在不同机器上难以复现同一套技能集合。

Proposed Solution

复用 vercel-labs/skills 的 lockfile 机制,新增分层真源与统一同步:

  • 本地真源:.claude/skills(维护自研 skill,已兼容 vercel-labs/skills 格式)
  • 外部依赖真源:skills-lock.json(直接复用 npx skills 的 lockfile 格式,字段包含 sourcecomputedHash
  • scripts/agent_rules.py 增加 skills sync / skills check 子命令
  • skills sync:从 lockfile 恢复外部 skill(等价于 npx skills install),并同步自研 skill 到目标目录
  • skills check:校验本地真源 + lockfile 与目标目录的一致性
  • justfile 增加 agent-skills-sync 命令入口

Alternatives Considered

  1. 只做 .claude/skills 字节同步,不引入 lockfile
    问题:无法表达跨 repo 依赖来源与版本,协作复现能力不足。

  2. 完全切换到 npx skills 管理全部 skill
    问题:会打破当前 .claude/skills 自研工作流,迁移成本高。

  3. 自定义 lockfile 格式
    问题:与 vercel-labs/skills 生态不兼容,增加维护和认知成本。

Implementation Notes

  • 直接复用 npx skillsskills-lock.json 格式(versionskills.<name>.sourceskills.<name>.sourceTypeskills.<name>.computedHash),不自造 schema。
  • sourceType 当前仅需 github,后续按需扩展。
  • .claude/skills(自研)与 lockfile(外部依赖)管理范围明确区分,避免双向覆盖。
  • 对同名但非托管目录应"失败并提示",不要静默覆盖。
  • 同步逻辑必须跳过系统目录(如 .system)。
  • CI 增加 skills check 阶段,防止 PR 引入未同步状态。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions