mcpField
S
shunk031-manage-public-private-skills

shunk031-manage-public-private-skills

github.com/shunk031Agent 工作流071 次安装5 天前更新
代码仓库

关于 shunk031-manage-public-private-skills

用于管理 shunk031 的公开与私有 Agent Skill 的维护指南，面向修改、发布或排查 Skill 的开发者。它明确规定源仓库归属、安装副本处理及更新验证流程。

主要功能

  1. 01判定公开或私有仓库归属
  2. 02在源仓库工作树中修改
  3. 03核对远程、安装副本与会话版本
  4. 04说明发布后的同步流程
  5. 05规定目录布局与评估用例写法

适用场景

  1. 01定位某个 Skill 应在哪个仓库修改
  2. 02排查更新未生效或版本不一致
  3. 03发布 Skill 后同步安装副本

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shunk031/skills --skill shunk031-manage-public-private-skills

安装后在 Claude Code 中输入/shunk031-manage-public-private-skills确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
results.json
references/
eval-authoring.md

详细介绍

说明

阅读此 SKILL.md 后，请说：🧰 I read shunk031-manage-public-private-skills.

管理公开和私有技能

技能内容存放在两个专用仓库中。两个 dotfiles 仓库都不再存放技能内容，因此，要求修改某项技能，就意味着要修改其中一个技能仓库，而不是你当前可能所在的代码检出目录。

技能存放位置

仓库存放内容
shunk031/skills所有可发布的技能
shunk031/skills-private正文中提及内部主机、凭据、内部端点或组织内部流程的技能
shunk031/dotfilesreconcile 脚本和公开订阅。不含技能内容
shunk031/dotfiles-private私有订阅。不含技能内容

判断依据是关于技能正文的那个问题。为工作编写并不意味着技能是私有的；提及内部系统才意味着它是私有的。如果某项技能难以判断，优先归为私有，并说明原因。

处理请求

  1. 按名称确定技能。~/.agents/skills/<name> 是已安装的副本；它只能说明该技能存在，不能说明其源文件所在位置。
  2. 按照上述标准，或通过检查哪个仓库已包含该技能，确定其所属仓库。
  3. 在该仓库的任务工作树中操作。切勿编辑已安装的副本。
  4. 如果变更涉及两个技能仓库，请将工作树、提交和拉取请求分开，并说明它们的先后顺序。

切勿编辑已安装的副本

~/.agents/skills/<name> 是 skills CLI 写入的真实目录。它是一个副本，而非指向任何源文件的链接，因此在此处所做的编辑会在下一次 skills update 时被悄然丢弃。

这与旧的安排不同：当时技能池条目是指向 chezmoi 源树的符号链接，编辑实际使用的技能也会修改源文件。

验证当前运行的版本

诊断技能更新缺失或未生效时，请比较 GitHub 上订阅引用对应的当前内容、已安装的 ~/.agents/skills/<name> 副本，以及目标会话实际读取的内容。通过远程端解析当前 GitHub 提交或 blob；即使本地检出或 origin/main 与已安装副本一致，也可能已经过时。检查目标会话的记录或经授权的重新读取；仅文件已更新并不能证明会话已加载该文件。将任何无法进行的比较标记为未经验证。在建议同步之前，请区分尚未部署的变更与当前源文件已不再规定的行为。

从编辑到运行技能的循环

edit in the skill repository worktree
  → gates pass locally
  → pull request
  → merge
  → chezmoi apply on the machine, which runs skills add/update

chezmoi apply 会将 skills update 限制为每天运行一次，避免文件监视循环在每次保存时都执行获取。合并后立即强制更新：

DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply    # or: make skills-update
技能来源订阅处理
shunk031/skills仓库级订阅会发现新增项；对账脚本会移除上游删除报告中的名称，而警告未涵盖的重命名或情况则需将旧名称添加到 shunk031/dotfiles 中的 SKILLS_RETIRED_NAMES
shunk031/skills-private在 shunk031/dotfiles-private 中的 home/dot_config/agents/skills-private.allowlist 添加或移除对应条目
第三方仓库在 shunk031/dotfiles 中的 install/common/skills.sh 添加或移除所选条目

合并公开技能变更后，使用 DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply 或 make skills-update 绕过每日发现节流。常规对账会在一天内发现新增项，并移除 skills update 上游删除警告中报告的名称。对于重命名或警告未披露的删除，请保留 SKILLS_RETIRED_NAMES。

绝不要将私有技能的名称写入 shunk031/dotfiles。 这是一个公开仓库，仅名称本身就会泄露将该技能放入私有仓库原本意在隐藏的内部主机、服务或流程。对账脚本是公开的，并会继续保持公开；只有私有名称列表会移动。

对账器会在对账时读取已应用的私有文件，并将其中的条目追加到自己的公开列表中，因此两组条目会通过一次流程完成安装。只有公开来源的机器没有此文件，这是正常情况，不是错误。

该文件中只有行首的 # 才表示注释，因为条目可能带有用于固定分支或标签的 #<ref> 后缀。

容易出错的布局规则

  • 每个技能在 skills/<category>/<name>/ 下单独使用一个目录，并包含 SKILL.md。Frontmatter 中的 name 必须与叶目录名称一致。
  • 绝不要在仓库根目录放置 SKILL.md。skills CLI 会在此处停止发现，只返回该技能，导致安装器看不到其他所有技能。
  • 类别布局必须严格保持在 skills/ 下一级：skills/<category>/<name>/。
  • evals/evals.json 使用 Anthropic skill-creator 格式来定义可选行为案例。
  • 技能在运行时需要的脚本应放在技能目录内。CLI 会将整个技能目录复制到资源池中，因此目录外的内容在技能运行时不会存在。

编写 evals

行为案例放在 evals/evals.json 中。添加或更改案例时，请阅读 references/eval-authoring.md。此仓库不提供运行或评分这些案例的命令。

编写和审查 skill

编写一个 SKILL.md。不要创建针对各个 Agent 的变体：全局安装会在 ~/.agents/skills/<name> 保留一份规范副本，并让每个 Agent 指向它。

在共享的 skill 文案、评测提示词和跨 Agent 指引中，将其他 skill 称为 <skill-name> skill。不要将 Codex 的 $skill-name 或 Claude Code 的 /skill-name 调用语法用作通用引用。仅在记录特定 Agent 的调用语法时使用这些形式。

请使用两个 Agent 各自的 skill 创建 skill 来审查草稿，因为它们的意见各有价值：

  • Claude Code：/skill-creator
  • Codex：$skill-creator（其内置 skill，位于 ~/.codex/skills/.system/skill-creator）

完成前

运行所属仓库的检查，并说明每项更改属于哪个仓库。不要在命令输出、引用的差异内容和摘要中暴露凭据值——这点在私有仓库中尤其重要，因为评测提示词会以明文提交，必须使用占位符。

创建或更新拉取请求属于日常工作。合并、运行 chezmoi apply 和更改运行时状态则不属于日常工作：请先询问。

评论

支持 Markdown