skill-maintainer

技能维护者

概述

面向维护技能库的 Agent 的元技能库——无论是维护自己的技能、从外部仓库改编的技能，还是发布到共享仓库的技能。涵盖完整生命周期：编写 → 筛选 → 跟踪 → 同步 → 发布。

此技能编码了一套经过数十个技能验证的工作流。它与 Agent 无关：将工具名称（例如 write_file、terminal、delegate_task）替换为你所在平台的对应工具即可。清单跟踪、分层同步、并行差异分派、基于 cron 的漂移检测等模式适用于任何 Agent 运行时。

适用场景

• 从头创建新技能
• 从外部仓库或集合导入／改编技能
• 检查本地技能是否已与上游版本出现偏差
• 扫描未跟踪的外部工具依赖
• 将本地技能发布到共享仓库
• 设置每月自动同步检查
• 精简／清理不断累积的技能库

不适用于： 无需跟踪上游的一次性技能创建（直接使用你所在平台的技能编写工具即可）。当你有 ≥5 个技能或 ≥1 个外部依赖需要跟踪时，此技能才能发挥作用。

核心概念

三个同步层级

层级	方向	漂移内容	示例
1. 外部 → 本地	上游仓库 → 你的技能	上游添加功能、修复错误、更改 API	baoyu-skills v1.56 → v1.117
2. 本地 → 已发布仓库	你的技能 → 你的 GitHub 仓库	你在本地改进技能；仓库中的副本变得陈旧	本地技能新增标志；仓库中没有
3. 本地 → 独立仓库	你的技能 → 代码项目仓库	技能记录工作流；代码持续演进	技能描述 CLI v1；CLI 现已是 v3

这三个层级都需要跟踪。层级 1 是最常见的关注点。层级 2 最容易被遗忘——发布一次后，持续改进，仓库中的版本便会过时。

清单

在技能根目录下放置一个 UPSTREAM_MANIFEST.md 文件，跟踪每个有外部来源的技能。每个技能占一行，涵盖所有三个层级。文件格式请参阅 templates/upstream-manifest.md。

cron 作业

自动化脚本（scripts/upstream_check.py）每月运行一次，获取上游版本并报告漂移情况。请参阅 Cron 设置部分。

---

技能编写工作流

0. 创建前检查重叠

创建新技能前：

1. 列出目标类别中已有的技能
2. 检查是否有技能涵盖相同能力——如果有，扩展现有技能，而不是创建并列技能
3. 检查是否有已停用／退役的技能涵盖该能力——重新启用，而不是重复创建

1. 调研同类技能

阅读目标类别中 2–3 个现有技能，以匹配其语气、结构和 frontmatter 约定。

2. Frontmatter

每个技能都需要：

---
name: my-skill-name         # lowercase, hyphens, ≤64 chars
description: >              # ≤1024 chars, starts with trigger context
  Use when <trigger>. <one-line behavior>.
license: MIT
metadata:
  version: 1.0.0            # spec allows only name/description/license/
  author: your-name         # compatibility/metadata/allowed-tools top-level
  platforms: [linux, macos, windows]
---

3. 结构

# <Title>

## Overview          — what and why (1-2 paragraphs)
## When to Use       — bullet triggers + "Don't use for"
## <Topic sections>  — quick-reference tables, exact commands, recipes
## Common Pitfalls   — numbered list of mistakes and fixes
## Verification Checklist — checkbox list

4. 大小指南

• 描述：≤1024 个字符
• SKILL.md 总计：≤100k 个字符（目标为 8–15k）
• 大量内容／特定分支内容 → references/*.md，并从 SKILL.md 链接到这些文件
• 脚本 → scripts/*.py，确保结果确定；尽可能只使用标准库

5. 质量原则

1. 优化流程的可预测性——如果某一行不会改变 Agent 的行为，就删掉它
2. 以完成标准结束每个步骤——“已核对每个修改过的文件”胜过“总结更改”
3. 将规则与其约束的概念放在一起——不要把同一个想法分散在文件各处
4. 使用有力的引导词——用“紧密循环”“示踪子弹”“根本原因”代替冗长解释
5. 删减重复内容和无效内容——每个含义只保留一个真实来源
6. 警惕过早完成——如果 Agent 匆忙完成某个步骤，就明确其完成标准

常见质量问题：过早完成、重复、沉积（过时内容）、膨胀（始终可见的内容过多）、无效文本。

6. 验证

• Frontmatter 能解析为 YAML，从字节 0 开始，并以 \n---\n 结束
• 包含 name 和 description，且 description ≤1024 个字符
• 结束的 --- 后有非空正文

7. 更新清单

如果技能有外部来源（改编自上游、封装第三方工具或已发布到仓库），请在 UPSTREAM_MANIFEST.md 中添加一行。这是强制要求——未跟踪的技能在每月同步检查中不可见。仅当技能完全原创且没有任何外部依赖时，才跳过清单。

---

技能整理工作流

1. 清点并分类

从外部集合移植技能时，对每个技能进行分类：

类别	操作
保留 — 独特、有价值且没有重叠	改编为你的格式
重复 — 你已有等效技能	合并独特部分或跳过
单薄／指针 — 只有 URL，没有实际内容	跳过
新奇内容 — 笑话／玩具示例，没有实用价值	跳过
能力层／路由器 — 安装程序加路由器，委托给上游 CLI	评估每个后端；不要一概替换原生技能

2. 评估重叠

将每个候选技能与现有技能进行比较。若两个技能重叠，除非外部技能能带来明确价值，否则优先采用你的原生技能。若要合并：将独特内容补充到现有技能中，丢弃外部副本。

3. 改编为你的格式

Frontmatter： 删除所有框架特有字段。保留 name、description、version（改编后递增）和 author（例如 "Source (adapted)"）。

正文： 完全重写，不要复制粘贴：

• 将所有非英语内容翻译成英语
• 删除框架特有的引用、沙箱路径和专有工具名称
• 重组为你的标准章节（使用时机、正文、注意事项、验证）
• 保留所有领域细节——准确的十六进制代码、像素尺寸、字体名称、时间信息、禁用模式——这些才是技能的价值所在
• 添加实用的触发词

4. 质量审查

# Non-English characters remaining (if source was non-EN)
grep -cP '[\x{4e00}-\x{9fff}]' SKILL.md
# Framework jargon remaining
grep -c 'framework-specific-term\|upstream-field' SKILL.md
# Version/author consistency
grep '^version:\|^author:' SKILL.md

5. 放入正确的类别

使用现有类别。不要随意创建新的顶级类别。

6. 更新清单

为每个改编的技能在 UPSTREAM_MANIFEST.md 中添加一行。条目类型见“上游跟踪”部分。

---

上游跟踪清单

在技能根目录维护 UPSTREAM_MANIFEST.md。每个具有外部来源的技能占一行。完整模板见 templates/upstream-manifest.md。

条目类型 — 选择正确的表格

类型	跟踪内容	审查方法
改编的技能	从上游技能仓库改编的技能内容	对比上游 SKILL.md，比较版本字段
引擎依赖	封装第三方 CLI／pip 工具的技能	对比 tool --version 与 GitHub releases
跟踪引擎的技能	围绕第三方引擎构建的原创技能	pip show <pkg> + GitHub releases
第三方技能	从外部仓库改编（并非专门的技能仓库）	获取 README／最新版本，比较概念
已发布的技能	推送到你的仓库的本地技能	对比本地版本与仓库副本的差异

原创且没有任何外部依赖的技能无需加入清单。

PORT_NOTES 模式（复杂改编的黄金标准）

对于结构改动较大的技能，请在技能目录中维护 PORT_NOTES.md：

# Port Notes — <skill-name>

Ported from <repo-url> v<upstream-version>.

## Changes from upstream
| Change | Upstream | Ours |

### What was preserved
<list of verbatim-copied files>

## Syncing with upstream
<exact curl/diff commands>
<files safe to overwrite vs requiring manual merge>

---

同步审查工作流

每月运行一次，或在收到提示时运行。

1. 阅读清单

记录上次检查日期。找出过期条目（上次同步距今 >60 天）。

2. 第 1 层 — 外部 → 本地

对每项改编后的技能：

1. 获取上游版本（原始 GitHub URL 或 GitHub API）
2. 与清单中固定的版本进行比较
3. 如果不同，对来源进行分类并采用相应的同步策略：

来源类型	同步方式
有版本、以原样内容为主	原样覆盖文件，合并改编后的文件
无版本、全面重写	保留我们的版本——仅通过差异比较查找新增的领域内容
持续演进	合并内容——添加上游章节，保留本地连接配置
已归档／已迁移	仅更新 URL——上游格式可能已更改
活跃度低	检查一次，通常无需处理

3. 第 2 层 — 本地 → 已发布的仓库

对每项已发布的技能，使用 diff 比较本地副本与仓库副本。如果本地版本更新，则重新发布（去品牌化、通用化并推送）。

4. 第 3 层 — 本地 → 独立仓库

对于与代码仓库相关的技能，检查该仓库的工作流／CLI 是否已更改。

5. 引擎依赖项扫描

# List installed CLI binaries
for tool in <your-tools>; do
  path=$(which $tool 2>/dev/null) && echo "$tool: $path" || echo "$tool: not installed"
done

# List pip packages
for pkg in <your-packages>; do
  pip show $pkg 2>/dev/null | grep -E '^Version:'
done

# Check latest releases
curl -s https://api.github.com/repos/<owner>/<repo>/releases/latest | grep tag_name

与清单交叉核对——任何为技能提供支持但未列入清单的已安装工具，都是未跟踪的依赖项。请将其添加进去。

6. 更新清单

记录最后检查日期、新的上游版本以及所执行的任何同步操作。

并行差异比较分派

同时审计多个上游来源时：

1. 一次性批量获取所有上游文件
2. 按来源分派并行子 Agent，进行差异比较和分类
3. 自行处理简单更新（URL 修正、原样覆盖）
4. 收集结构化建议（保留／合并／重新移植）
5. 根据建议执行合并

这样可以将串行的 30 分钟审计缩短为并行的 5 分钟。

---

将技能发布到公共仓库

去品牌化

发布源自特定客户端／组织的技能时：

1. 使用 grep 搜索所有文件中的品牌引用
2. 删除或泛化：品牌名称、专有调色板、监管引用、组织内部文件路径和品牌专属样式
3. 删除品牌专属的参考文件
4. 将具体金额替换为通用表述
5. 使用 grep 确认内容已清理干净
6. 提升已发布版本的版本号

通用化

特定平台的术语	替换为
平台工具名称（image_generate 等）	通用描述
平台元数据字段	从 frontmatter 中移除
硬编码路径	带回退值的环境变量，或 <skill_dir>/...
兄弟技能依赖项	带回退值的环境变量解析
特定平台的交付方式	通用表述“通过用户的渠道发送”

测试已发布版本

• 脚本可解析：python3 -c "import ast; ast.parse(open('scripts/main.py').read())"
• 导入可解析：python3 -c "from script import main_func"
• 确认可平稳降级（模拟缺少可选依赖项的情况）

互斥性

在可按需挑选的仓库中，每项技能都必须自成一体且可独立运行，即使这会导致兄弟技能之间的代码重复。切勿提取共享模块——仅克隆一项技能的用户不应依赖另一项技能中的文件。

---

Cron 设置 — 自动检测偏差

设置每月运行的 cron 作业，自动检查上游偏差。

1. 复制清单模板

cp templates/upstream-manifest.md /path/to/your/skills/UPSTREAM_MANIFEST.md

编辑模板，列出你的实际技能、上游仓库和版本。

2. 复制检查脚本

cp scripts/upstream_check.py /path/to/your/scripts/

脚本直接从 UPSTREAM_MANIFEST.md 读取第 1 层和第 2 层表格。没有硬编码的技能列表——清单是唯一真实来源。

引擎依赖项（ENGINE_DEPS）在脚本文件本身中配置，而不是在清单中。这是一条有意设置的安全边界：清单内容是可能被外部编辑的 Markdown，因此我们不会执行从中派生的 shell 命令。添加类似以下的条目：

ENGINE_DEPS = [
    {"name": "my-cli-tool", "command": ["my-cli", "--version"], "version_regex": r"(\d+\.\d+\.\d+)"},
    {"name": "my-pip-pkg", "command": ["pip", "show", "my-pip-pkg"], "version_regex": r"(\d+\.\d+\.\d+)"},
]

命令会以列表形式传递（绝不使用 shell=True），以防止来自不可信配置的 shell 注入。

你可能还需要在脚本顶部设置 SKILLS_ROOT 和 LAYER_2_REPO，或者通过 SKILLS_ROOT 和 LAYER_2_REPO 环境变量设置。

3. 设置 cron 任务

使用通用 cron 调度器（根据你的平台进行调整）：

# Monthly upstream sync check — 9am on the 1st
0 9 1 * * /path/to/python3 /path/to/scripts/upstream_check.py

或者使用 Agent 平台的 cron 工具：

{
  "name": "Monthly Upstream Sync Check",
  "schedule": "0 9 1 * *",
  "prompt": "Run the upstream sync check script at /path/to/scripts/upstream_check.py. Report any drift detected. If drift is found, summarize which skills need attention and what changed upstream.",
  "no_agent": true
}

如果所有内容都同步，脚本会以 0 退出；如果检测到偏差，则以 1 退出。非空 stdout 会作为消息发送；空 stdout 表示静默（无需报告）。

4. 脚本检查的内容

• 第 1 层：解析清单表格，从 GitHub 获取上游 SKILL.md，并比较版本字段。对于没有版本字段的来源，通过 GitHub API 报告最近提交日期。使用仓库的默认分支（回退到 master）。除非清单行带有可选的 Upstream path 列，否则会猜测上游文件位于 skills/<name>/SKILL.md——对于布局不同的上游，请添加该列，否则每次检查都会警告“无法获取上游文件”。
• **第 2 层：**同时使用版本字段和 SHA-256 内容哈希比较本地仓库与已发布仓库。既能发现版本偏差（版本号不同），也能发现内容偏差（版本相同但内容不同——例如，你在本地编辑了内容，却没有更新版本或重新发布）。
• **引擎依赖项：**运行已配置的版本检查命令（列表形式，不使用 shell），并提取版本字符串。

5. 处理偏差报告

cron 报告偏差时：

1. 阅读报告——哪些技能发生了变化，版本差异是什么
2. 将上游文件获取到临时目录
3. 将每个文件分类为逐字复制（覆盖）或经过改编（合并）
4. 对于合并：以上游内容为基础，重新应用本地改编
5. 运行术语检查——搜索应该不存在的上游专用术语
6. 更新 PORT_NOTES.md，记录同步日志
7. 更新清单中的版本、日期和状态

---

扩展现有技能还是创建新技能

当新能力与现有技能重叠时：

1. 现有技能是否涵盖核心能力？ → 将缺失部分（参考文件、脚本、路由条目）添加到该技能中
2. 是否需要根本不同的工作流／工具集？ → 可以考虑新建技能，但应先说明理由
3. 是否只是现有基础设施上的薄层？ → 使用参考文件和可选脚本，而不是新建技能

当某个子主题规模增大、足以成为独立技能时，所属的总括技能必须指向新技能，而不是保留重复内容。将内联细节替换为指引：“→ 有关……，请参阅专用的 <skill-name> 技能。”重复内容会逐渐偏离；指引则能确保只有一个真实来源。

---

常见问题

1. 浅层移植毫无价值 — 如果技能使用源项目术语、缺少触发条件，也没有重组内容，那就毫无用处。务必进行完整的适配。
2. 技能膨胀 — 不要移植 139 个技能，35 个有价值的就够了。适配前，果断删除内容单薄、只作指引、重复或新奇噱头类技能。
3. 复制粘贴陷阱 — 源格式永远不是目标格式。要重组正文，而不只是翻译标题。
4. 缺少领域细节 — 精确的十六进制代码、像素尺寸、字体粗细、禁止使用的模式才是技能的核心。删掉这些就会毁掉技能的价值。
5. 忽视重叠 — 添加技能前务必检查现有技能。两个技能做同一件事，不如一个。
6. 忽视反向同步（第 2 层） — 发布后，你仍会在本地继续改进。没有清单跟踪，仓库副本就会悄然过时。务必记录推送日期。
7. “保留我们的版本”是合理选择 — 并非每个上游差异都需要合并。如果你的版本包含上游版本的全部内容，就记录决定并继续推进。
8. 合并子 Agent 需要明确的保留清单 — 如果没有列出绝不能删除的内容，合并子 Agent 可能会用上游版本覆盖所有内容。
9. 引擎跟踪类技能需要不同的同步方式 — 比较已安装版本与最新发布版本，而不是比较 SKILL.md 内容。即使 SKILL.md 是最新的，过时的二进制文件也会导致技能失效。
10. 隐性身份验证依赖 — 某个后端在开发者的桌面上可能“开箱即用”，但在服务器上可能需要 Cookie、二维码登录或浏览器扩展。必须明确说明身份验证的限制。
11. 技能原子性原则 — 保持技能原子化（每个技能只具备一种能力）。Agent 在运行时串联技能，而不是在设计时串联。
12. 可移植仓库中的相互独立性 — 每个技能都必须自成一体。不要提取共享模块；重复是保持独立的代价。
13. 沉积 — 技能应该随着时间推移变得更简洁或更精确。添加规则时，删除它所取代的旧表述。
14. 无效措辞 — “小心”“仔细”之类的说法很少能改变行为。应将其替换为可检查的完成标准。

验证清单

• 已检查重叠 — 没有现有技能涵盖相同能力
• Frontmatter 有效 — 以 --- 开头，以 \n---\n 结尾，并可解析为 YAML
• 存在 name（≤64 个字符，仅限小写字母和连字符）和 description（≤1024 个字符）
• 结构：概述 → 适用场景 → 正文 → 常见问题 → 验证
• 每个步骤都有可检查的完成标准
• 没有无效措辞或重复规则
• 文件总长度 ≤100k 个字符（目标为 8–15k）
• 大篇幅参考资料放在链接的 references/*.md 文件中
• 脚本具有确定性，并尽可能只使用纯标准库
• 如果技能有外部来源，已更新 UPSTREAM_MANIFEST.md
• 已为复杂适配创建 PORT_NOTES.md
• 术语检查已通过 — 适配文件中没有上游专用术语
• 已对发布版本去品牌化、泛化并完成测试
• 已配置每月一次的 Cron 作业来检测偏移
• tests/test_upstream_check.py（此技能自身的测试套件）已通过 — 在技能目录中运行 python3 -m pytest tests/ -q