Back to Details

skill-maintainer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Maintainer

技能维护者

Overview

概述

A meta-skill for agents who maintain a library of skills — their own, adapted from external repos, or published to a shared repo. Covers the full lifecycle: authoring → curating → tracking → syncing → publishing.
This skill encodes a workflow built and battle-tested across dozens of skills. It is agent-agnostic: replace tool names (e.g. 
write_file
, 
terminal
, 
delegate_task
) with your platform's equivalents. The patterns — manifest tracking, layered sync, parallel diff dispatch, cron-based drift detection — transfer to any agent runtime.
这是一款面向维护技能库的Agent的元技能，技能库中的技能可以是自研的、从外部仓库适配的，或是发布到共享仓库的。它覆盖技能全生命周期：创作 → 筛选 → 跟踪 → 同步 → 发布。
该技能编码了一套经过数十个技能实战验证的工作流。它与Agent平台无关：只需将工具名称（如
write_file
、
terminal
、
delegate_task
）替换为你平台的等效工具即可。其中的模式——manifest跟踪、分层同步、并行差异分发、基于cron的变更差异检测——可迁移到任何Agent运行时环境。

When to Use

适用场景

  • Creating a new skill from scratch
  • Importing/adapting skills from an external repo or collection
  • Checking if local skills have drifted from upstream
  • Scanning for untracked external tool dependencies
  • Publishing a local skill to a shared repo
  • Setting up automated monthly sync checks
  • Tightening/pruning an accumulated skill library
Don't use for: one-off skill creation with no upstream tracking need (just use your platform's skill-authoring tool directly). This skill adds value when you have ≥5 skills or ≥1 external dependency to track.
  • 从零开始创建新技能
  • 从外部仓库或技能集合导入/适配技能
  • 检查本地技能与上游版本是否存在变更差异
  • 扫描未跟踪的外部工具依赖
  • 将本地技能发布到共享仓库
  • 设置月度自动同步检查
  • 精简/清理累积的技能库
不适用场景： 无需跟踪上游的一次性技能创建（直接使用平台的技能创作工具即可）。当你拥有≥5个技能或≥1个需要跟踪的外部依赖时，该技能才能体现价值。

Core Concepts

核心概念

The three sync layers

三层同步架构

LayerDirectionWhat driftsExample
1. External → LocalUpstream repo → your skillUpstream adds features, fixes bugs, changes APIbaoyu-skills v1.56 → v1.117
2. Local → Published repoYour skill → your GitHub repoYou improve locally; repo copy goes staleskill gets new flags locally; repo doesn't
3. Local → Standalone repoYour skill → a code project repoSkill documents a workflow; the code evolvesskill describes CLI v1; CLI is now v3
All three need tracking. Layer 1 is the most common concern. Layer 2 is the most commonly forgotten — publish once, keep improving, repo goes stale.
层级方向变更差异来源示例
1. 外部 → 本地上游仓库 → 你的技能上游新增功能、修复Bug、变更APIbaoyu-skills v1.56 → v1.117
2. 本地 → 已发布仓库你的技能 → 你的GitHub仓库你在本地优化技能，但仓库副本已过时本地技能新增参数，但仓库版本未更新
3. 本地 → 独立项目仓库你的技能 → 代码项目仓库技能记录了工作流，但代码已迭代技能描述CLI v1，但CLI已升级到v3
这三层都需要跟踪。层级1是最常见的关注点，层级2则最容易被遗忘——发布一次后持续在本地优化，导致仓库副本默默过时。

The manifest

Manifest文件

A single 
UPSTREAM_MANIFEST.md
file at your skills root tracks every skill with external provenance. One row per skill, covering all three layers. See 
templates/upstream-manifest.md
for the file format.
在技能根目录下的单个
UPSTREAM_MANIFEST.md
文件，用于跟踪所有具有外部来源的技能。每个技能占一行，覆盖上述三层同步。文件格式可参考
templates/upstream-manifest.md
。

The cron job

Cron任务

An automated script (
scripts/upstream_check.py
) runs monthly, fetches upstream versions, and reports drift. See the Cron Setup section.
自动化脚本
scripts/upstream_check.py
每月运行一次，获取上游版本并报告变更差异。具体设置请查看Cron配置章节。

Skill Authoring Workflow

技能创作工作流

0. Check for overlap before creating

0. 创建前检查重叠性

Before creating a new skill:
  1. List existing skills in the target category
  2. Check if any cover the same capability — if so, extend the existing skill rather than creating a sibling
  3. Check if any disabled/retired skill covers it — re-enable instead of duplicating
创建新技能前：
  1. 列出目标分类下的现有技能
  2. 检查是否有技能覆盖相同能力——如果有，扩展现有技能而非创建同类技能
  3. 检查是否有已禁用/废弃的技能覆盖该能力——重新启用而非重复创建

1. Survey peers

1. 参考同类技能

Read 2–3 existing skills in the target category to match tone, structure, and frontmatter conventions.
阅读目标分类下2-3个现有技能，匹配其语气、结构和前置元数据规范。

2. Frontmatter

2. 前置元数据

Every skill needs:
yaml
---
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]
---
每个技能都需要包含：
yaml
---
name: my-skill-name         # 小写、连字符分隔、≤64字符
description: >              # ≤1024字符，以触发场景开头
  当<触发条件>时使用。<一行描述行为>。
license: MIT
metadata:
  version: 1.0.0            # 规范仅允许name/description/license/
  author: your-name         # compatibility/metadata/allowed-tools为顶级字段
  platforms: [linux, macos, windows]
---

3. Structure

3. 结构规范

undefined
undefined

<Title>

<标题>

Overview — what and why (1-2 paragraphs)

概述 — 技能用途与价值（1-2段）

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

验证清单 — 复选框列表

undefined
undefined

4. Size guidelines

4. 篇幅指南

  • Description: ≤1024 chars
  • Total SKILL.md: ≤100k chars (aim for 8–15k)
  • Bulky/branch-specific material → 
    references/*.md
    , linked from SKILL.md
  • Scripts → 
    scripts/*.py
    , deterministic, pure stdlib where possible
  • 描述：≤1024字符
  • 整个SKILL.md文件：≤100k字符（目标8–15k）
  • 大篇幅/分支特定内容 → 放入
    references/*.md
    ，并在SKILL.md中链接
  • 脚本 → 放入
    scripts/*.py
    ，确保确定性，尽可能使用标准库

5. Quality principles

5. 质量原则

  1. Optimize for process predictability — if a line doesn't change agent behavior, cut it
  2. End steps with completion criteria — "every modified file accounted for" beats "summarize changes"
  3. Co-locate rules with the concept they govern — don't scatter one idea across the file
  4. Use strong leading words — "tight loop," "tracer bullet," "root cause" over long explanations
  5. Prune duplication and no-ops — keep each meaning in one source of truth
  6. Watch for premature completion — if agents rush a step, sharpen its completion criterion
Common quality failures: premature completion, duplication, sediment (stale lines), sprawl (too much always-visible material), no-op prose.
  1. 优化流程可预测性 — 如果某行内容不会改变Agent行为，删除它
  2. 步骤需包含完成标准 — "所有修改文件已核对"比"总结变更"更清晰
  3. 规则与对应概念就近放置 — 不要将同一概念的规则分散在文件各处
  4. 使用明确引导词 — 用"快速循环"、"探路测试"、"根本原因"替代冗长解释
  5. 消除重复与无效内容 — 每个信息只保留一个权威来源
  6. 警惕提前完成 — 如果Agent会跳过步骤，需明确完善完成标准
常见质量问题：提前完成、内容重复、沉淀（过时内容）、冗余（过多无关可见内容）、无效描述。

6. Validate

6. 验证

  • Frontmatter parses as YAML, starts at byte 0, closes with 
    \n---\n
  • name
    and 
    description
    present, description ≤1024 chars
  • Non-empty body after closing 
    ---
  • 前置元数据可解析为YAML，从字节0开始，以
    \n---\n
    结尾
  • 包含
    name
    和
    description
    ，且描述≤1024字符
  • 关闭
    ---
    后有非空正文

7. Update the manifest

7. 更新Manifest

If the skill has external provenance (adapted from upstream, wraps a third-party tool, or published to a repo), add a row to 
UPSTREAM_MANIFEST.md
. This is mandatory — an untracked skill is invisible to the monthly sync check. Skip the manifest only for original skills with zero external dependency.
如果技能有外部来源（改编自上游、封装第三方工具、或发布到仓库），需在
UPSTREAM_MANIFEST.md
中添加一行。这是强制要求——未跟踪的技能无法被月度同步检查识别。仅当技能为完全自研且无任何外部依赖时，可跳过此步骤。

Skill Curation Workflow

技能筛选工作流

1. Inventory and classify

1. 盘点与分类

When porting skills from an external collection, classify each:
ClassAction
Keep — unique, valuable, no overlapAdapt to your format
Duplicate — you already have an equivalentMerge unique parts or skip
Thin/pointer — just a URL, no real contentSkip
Novelty — joke/toy, no practical valueSkip
Capability-layer/router — installer + router delegating to upstream CLIsEvaluate each backend; don't wholesale replace native skills
从外部集合移植技能时，对每个技能进行分类：
类别操作
保留 — 独特、有价值、无重叠适配为你的格式
重复 — 已有等效技能合并独特内容或跳过
精简/指向型 — 仅含URL，无实质内容跳过
娱乐型 — 玩笑/玩具技能，无实用价值跳过
能力层/路由型 — 安装器+路由，委托给上游CLI评估每个后端，不要全盘替换原生技能

2. Assess overlap

2. 评估重叠性

Compare each candidate against existing skills. When two overlap, prefer your native one unless the external one adds clear value. If merging: patch the existing skill with unique content, discard the external copy.
将每个候选技能与现有技能对比。当两者重叠时，优先使用原生技能，除非外部技能有明确增值。若合并：将独特内容补丁到现有技能，丢弃外部副本。

3. Adapt to your format

3. 适配为你的格式

Frontmatter: strip all framework-specific fields. Keep 
name
, 
description
, 
version
(bump for adapted), 
author
(e.g. "Source (adapted)").
Body: full rewrite, not copy-paste:
  • Translate all non-English content to English
  • Strip framework-specific references, sandbox paths, proprietary tool names
  • Restructure into your standard sections (When to use, body, pitfalls, verification)
  • Preserve all domain detail — exact hex codes, pixel dimensions, font names, timing, forbidden patterns — these ARE the skill's value
  • Add practical trigger words
前置元数据： 移除所有框架特定字段。保留
name
、
description
、
version
（适配后需升级版本）、
author
（例如"原作者（已适配）"）。
正文： 完全重写，而非复制粘贴：
  • 将所有非英文内容翻译为英文
  • 移除框架特定引用、沙箱路径、专有工具名称
  • 重构为你的标准章节（适用场景、正文、陷阱、验证）
  • 保留所有领域细节 — 精确的十六进制代码、像素尺寸、字体名称、时间要求、禁用模式——这些是技能的核心价值
  • 添加实用触发词

4. Quality audit

4. 质量审计

bash
undefined
bash
undefined

Non-English characters remaining (if source was non-EN)

检查是否残留非英文字符（若源文件为非英文）

grep -cP '[\x{4e00}-\x{9fff}]' SKILL.md
grep -cP '[\x{4e00}-\x{9fff}]' SKILL.md

Framework jargon remaining

检查是否残留框架术语

grep -c 'framework-specific-term|upstream-field' SKILL.md
grep -c 'framework-specific-term|upstream-field' SKILL.md

Version/author consistency

检查版本/作者一致性

grep '^version:|^author:' SKILL.md
undefined
grep '^version:|^author:' SKILL.md
undefined

5. Place in correct category

5. 放入正确分类

Use existing categories. Don't invent new top-level categories casually.
使用现有分类，不要随意创建新的顶级分类。

6. Update manifest

6. 更新Manifest

Add a row to 
UPSTREAM_MANIFEST.md
for every adapted skill. See the Upstream Tracking section for entry types.
为每个适配的技能在
UPSTREAM_MANIFEST.md
中添加一行。具体条目类型请查看上游跟踪章节。

Upstream Tracking Manifest

上游跟踪Manifest

Maintain 
UPSTREAM_MANIFEST.md
at your skills root. One row per skill with external provenance. See 
templates/upstream-manifest.md
for the full template.
在技能根目录维护
UPSTREAM_MANIFEST.md
，每个具有外部来源的技能占一行。完整模板请参考
templates/upstream-manifest.md
。

Entry types — pick the right table

条目类型——选择对应表格

TypeWhat it tracksAudit method
Adapted skillSkill content adapted from an upstream skill repoDiff upstream SKILL.md, compare version fields
Engine dependencySkill wraps a third-party CLI/pip tool
tool --version
vs GitHub releases
Engine-tracking skillOriginal skill built around a third-party engine
pip show <pkg>
+ GitHub releases
Third-party skillAdapted from external repo (not a skill repo per se)Fetch README/latest, compare concepts
Published skillLocal skill pushed to your repo
diff
local vs repo copy
Skip the manifest for original skills with zero external dependency.
类型跟踪内容审计方式
适配技能改编自上游技能仓库的技能内容对比上游SKILL.md与版本字段
引擎依赖封装第三方CLI/pip工具的技能
tool --version
对比GitHub发布版本
引擎跟踪技能基于第三方引擎构建的自研技能
pip show <pkg>
+ GitHub发布版本
第三方技能改编自外部仓库（非技能仓库）获取README/最新版本，对比核心概念
已发布技能推送到仓库的本地技能
diff
本地与仓库副本
跳过Manifest的情况： 完全自研且无任何外部依赖的技能。

The PORT_NOTES pattern (gold standard for complex adaptations)

PORT_NOTES模式（复杂适配的黄金标准）

For skills with significant structural changes, maintain 
PORT_NOTES.md
inside the skill directory:
markdown
undefined
对于有重大结构变更的技能，在技能目录下维护
PORT_NOTES.md
：
markdown
undefined

Port Notes — <skill-name>

移植说明 — <skill-name>

Ported from <repo-url> v<upstream-version>.
从<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>

---
<精确的curl/diff命令> <可安全覆盖的文件 vs 需要手动合并的文件>

---

Sync Audit Workflow

同步审计工作流

Run monthly or when prompted.
每月运行一次，或按需触发。

1. Read the manifest

1. 读取Manifest

Note last-checked dates. Identify stale rows (last sync >60 days).
查看上次检查日期，识别过时条目（上次同步>60天）。

2. Layer 1 — External → Local

2. 层级1 — 外部 → 本地

For each adapted skill:
  1. Fetch upstream version (raw GitHub URL or GitHub API)
  2. Compare to pinned version in manifest
  3. If different, classify the source and apply the right sync strategy:
Source typeSync approach
Versioned, verbatim-heavyOverwrite verbatim files, merge adapted files
Unversioned, full rewriteKeep ours — diff for new domain content only
Actively evolvingContent merge — add upstream sections, preserve local wiring
Archived/movedUpdate URLs only — upstream may have changed format
Low activityOne-time check, usually nothing to do
对于每个适配技能：
  1. 获取上游版本（原始GitHub URL或GitHub API）
  2. 与Manifest中固定的版本对比
  3. 若版本不同，根据来源类型应用对应同步策略：
来源类型同步方式
版本化、高逐字复用覆盖逐字文件，合并适配文件
无版本化、完全重写保留本地版本——仅对比新增领域内容
持续迭代内容合并——添加上游章节，保留本地适配逻辑
归档/迁移仅更新URL——上游可能已变更格式
低活跃度一次性检查，通常无需操作

3. Layer 2 — Local → Published repo

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

For each published skill, 
diff
local vs repo copy. If local is ahead, re-publish (debrand, generalize, push).
对于每个已发布技能，使用
diff
对比本地与仓库副本。若本地版本更新，重新发布（去品牌化、通用化、推送）。

4. Layer 3 — Local → Standalone repo

4. 层级3 — 本地 → 独立项目仓库

For skills tied to code repos, check if the repo's workflow/CLI has changed.
对于绑定代码仓库的技能，检查仓库的工作流/CLI是否变更。

5. Engine dependency scan

5. 引擎依赖扫描

bash
undefined
bash
undefined

List installed CLI binaries

列出已安装的CLI二进制文件

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

List pip packages

列出pip包

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

Cross-reference with manifest — any installed tool that powers a skill but
isn't in the manifest is an untracked dependency. Add it.
curl -s https://api.github.com/repos/<owner>/<repo>/releases/latest | grep tag_name

与Manifest交叉核对——任何为技能提供支持但未在Manifest中记录的已安装工具，均为未跟踪依赖，需添加到Manifest。

6. Update manifest

6. 更新Manifest

Record last-checked date, new upstream version, any sync actions taken.
记录上次检查日期、新上游版本、已执行的同步操作。

Parallel diff dispatch

并行差异分发

When auditing multiple upstream sources simultaneously:
  1. Fetch all upstream files in one batch
  2. Dispatch parallel subagents per source to diff and classify
  3. Handle simple updates (URL fixes, verbatim overwrites) yourself
  4. Collect structured recommendations (keep/merge/re-port)
  5. Execute merges based on recommendations
This turns a serial 30-minute audit into a 5-minute parallel one.
同时审计多个上游来源时：
  1. 批量获取所有上游文件
  2. 为每个来源分配并行子Agent进行差异对比与分类
  3. 自行处理简单更新（URL修复、逐字覆盖）
  4. 收集结构化建议（保留/合并/重新移植）
  5. 根据建议执行合并操作
这将原本串行30分钟的审计缩短为5分钟的并行操作。

Publishing Skills to a Public Repo

将技能发布到公共仓库

Debranding

去品牌化

When publishing a skill derived from a client/org-specific source:
  1. Grep for brand references across all files
  2. Remove or genericize: brand names, proprietary palettes, regulatory references, org-internal file paths, house styles
  3. Remove brand-specific reference files
  4. Replace specific dollar amounts with generic terms
  5. Verify clean with grep
  6. Bump version for the published version
发布源自客户/组织特定来源的技能时：
  1. 搜索所有文件中的品牌引用
  2. 删除或通用化：品牌名称、专有配色、合规引用、组织内部文件路径、专属风格
  3. 删除品牌特定参考文件
  4. 将具体金额替换为通用术语
  5. 再次搜索验证无残留
  6. 为发布版本升级版本号

Generalizing

通用化

Platform-specific termReplace with
Platform tool names (
image_generate
, etc.)		Generic description
Platform metadata fieldsRemove from frontmatter
Hardcoded pathsEnv var with fallback, or 
<skill_dir>/...
Sibling skill dependenciesEnv var resolution with fallbacks
Platform-specific deliveryGeneric "send via the user's channel"
平台特定术语替换为
平台工具名称（
image_generate
等）		通用描述
平台元数据字段从前置元数据中移除
硬编码路径环境变量+回退值，或
<skill_dir>/...
同类技能依赖环境变量解析+回退值
平台特定交付方式通用描述“通过用户渠道发送”

Testing the published version

测试发布版本

  • Scripts parse: 
    python3 -c "import ast; ast.parse(open('scripts/main.py').read())"
  • Imports resolve: 
    python3 -c "from script import main_func"
  • Graceful degradation works (simulate missing optional deps)
  • 脚本可解析：
    python3 -c "import ast; ast.parse(open('scripts/main.py').read())"
  • 导入可解析：
    python3 -c "from script import main_func"
  • 优雅降级生效（模拟缺失可选依赖）

Mutual exclusivity

互斥性

In a pick-and-choose repo, each skill must be self-contained and runnable standalone, even at the cost of code duplication across siblings. Do NOT extract shared modules — a user who clones only one skill should not need a file from another.
在可选技能仓库中，每个技能必须独立可运行，即使这意味着同类技能间存在代码重复。不要提取共享模块——仅克隆单个技能的用户不应依赖其他技能的文件。

Cron Setup — Automated Drift Detection

Cron配置——自动变更差异检测

Set up a monthly cron job to automatically check for upstream drift.
设置月度Cron任务，自动检查上游变更差异。

1. Copy the manifest template

1. 复制Manifest模板

bash
cp templates/upstream-manifest.md /path/to/your/skills/UPSTREAM_MANIFEST.md
Edit it to list your actual skills, upstream repos, and versions.
bash
cp templates/upstream-manifest.md /path/to/your/skills/UPSTREAM_MANIFEST.md
编辑模板，列出你的实际技能、上游仓库和版本。

2. Copy the check script

2. 复制检查脚本

bash
cp scripts/upstream_check.py /path/to/your/scripts/
The script reads Layer 1 and Layer 2 tables directly from 
UPSTREAM_MANIFEST.md
. No hardcoded skill lists — the manifest is the single source of truth.
Engine dependencies (
ENGINE_DEPS
) are configured in the script file itself, not in the manifest. This is a deliberate security boundary: manifest content is markdown that could be externally edited, so we don't execute shell commands derived from it. Add entries like:
python
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+)"},
]
Commands are passed as lists (never 
shell=True
) to prevent shell injection from untrusted config.
You may also need to set 
SKILLS_ROOT
and 
LAYER_2_REPO
at the top of the script, or via the 
SKILLS_ROOT
and 
LAYER_2_REPO
env vars.
bash
cp scripts/upstream_check.py /path/to/your/scripts/
脚本直接从
UPSTREAM_MANIFEST.md
读取层级1和层级2的表格。无硬编码技能列表——Manifest是唯一权威来源。
引擎依赖（
ENGINE_DEPS
）在脚本文件中配置，而非Manifest。这是刻意设置的安全边界：Manifest是可能被外部编辑的Markdown内容，因此我们不会执行从Manifest衍生的Shell命令。添加如下条目：
python
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. Set up the cron job

3. 设置Cron任务

Using a generic cron scheduler (adapt to your platform):
undefined
使用通用Cron调度器（根据你的平台调整）：
undefined

Monthly upstream sync check — 9am on the 1st

月度上游同步检查 — 每月1日9点

0 9 1 * * /path/to/python3 /path/to/scripts/upstream_check.py

Or using an agent platform's cron tool:

```json
{
  "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
}
The script exits 0 if all in sync, 1 if drift detected. Non-empty stdout is delivered as the message; empty stdout means silent (nothing to report).
0 9 1 * * /path/to/python3 /path/to/scripts/upstream_check.py

或使用Agent平台的Cron工具：

```json
{
  "name": "月度上游同步检查",
  "schedule": "0 9 1 * *",
  "prompt": "运行位于/path/to/scripts/upstream_check.py的上游同步检查脚本。报告检测到的任何变更差异。若发现差异，总结需要关注的技能及上游变更内容。",
  "no_agent": true
}
脚本同步正常时返回0，检测到差异时返回1。非空标准输出将作为消息发送；空标准输出表示无内容需报告。

4. What the script checks

4. 脚本检查内容

  • Layer 1: parses manifest table, fetches upstream SKILL.md from GitHub, compares version fields. For sources without version fields, reports last commit date via GitHub API. Uses the repo's default branch (falls back to 
    master
    ). The upstream file location is guessed as 
    skills/<name>/SKILL.md
     unless the manifest row carries an optional 
    Upstream path
    column — add that column for upstreams with a different layout, or the check will warn "could not fetch upstream" every run.
  • Layer 2: compares local vs published repo using both version fields and SHA-256 content hashes. Catches version drift (different version numbers) AND content drift (same version, different content — e.g. you edited locally but didn't bump the version or re-publish).
  • Engine deps: runs configured version-check commands (list-form, no shell) and extracts version strings.
  • 层级1： 解析Manifest表格，从GitHub获取上游SKILL.md，对比版本字段。对于无版本字段的来源，通过GitHub API报告最后提交日期。使用仓库默认分支（回退为
    master
    ）。上游文件位置默认推测为
    skills/<name>/SKILL.md
    ，除非Manifest条目包含可选的
    Upstream path
    列——若上游布局不同，需添加该列，否则每次检查都会警告“无法获取上游内容”。
  • 层级2： 同时使用版本字段和SHA-256内容哈希对比本地与已发布仓库版本。可检测版本差异（版本号不同）和内容差异（版本号相同但内容不同——例如你在本地编辑但未升级版本或重新发布）。
  • 引擎依赖： 运行配置的版本检查命令（列表形式，无Shell）并提取版本字符串。

5. Handling drift reports

5. 处理差异报告

When the cron reports drift:
  1. Read the report — which skills changed, what's the version delta
  2. Fetch upstream files to a temp directory
  3. Classify each file as verbatim (overwrite) or adapted (merge)
  4. For merges: take upstream as base, re-apply local adaptations
  5. Run jargon check — grep for upstream-specific terms that should be absent
  6. Update PORT_NOTES.md with sync log
  7. Update manifest with new version, date, and status
当Cron报告差异时：
  1. 阅读报告——哪些技能变更，版本差异是什么
  2. 将上游文件下载到临时目录
  3. 将每个文件分类为逐字文件（可覆盖）或适配文件（需合并）
  4. 合并时：以上游版本为基础，重新应用本地适配
  5. 运行术语检查——搜索应移除的上游特定术语
  6. 更新PORT_NOTES.md，添加同步日志
  7. 更新Manifest，记录新版本、日期和状态

Extending vs Creating New Skills

扩展现有技能 vs 创建新技能

When a new capability overlaps with an existing skill:
  1. Does an existing skill cover the core capability? → Extend it with the missing piece (reference file, script, routing entry)
  2. Does it need a fundamentally different workflow/toolset? → New skill may be warranted, but justify it first
  3. Is it a thin layer on existing infrastructure? → Reference file + optional script, not a new skill
When a sub-topic grows large enough to warrant a dedicated skill, the umbrella skill MUST point to the new skill, not keep duplicate content. Replace inline detail with a pointer: "→ See dedicated 
<skill-name>
skill for: ..." Duplicate content drifts; a pointer ensures one source of truth.
当新能力与现有技能重叠时：
  1. 现有技能是否覆盖核心能力？ → 扩展现有技能，添加缺失部分（参考文件、脚本、路由条目）
  2. 是否需要完全不同的工作流/工具集？ → 可能需要创建新技能，但需先说明理由
  3. 是否是现有基础设施的薄包装？ → 使用参考文件+可选脚本，而非创建新技能
当子主题增长到需要独立技能时，父技能必须指向新技能，而非保留重复内容。将内联细节替换为指向：“→ 查看专用
<skill-name>
技能获取：...” 重复内容会产生变更差异，而指向可确保单一权威来源。

Pitfalls

常见陷阱

  1. Shallow ports are worthless — a skill with source jargon, missing triggers, and no restructuring helps no one. Always do a full adaptation pass.
  2. Skill inflation — don't port 139 skills when 35 are valuable. Ruthlessly delete thin/pointer/duplicate/novelty skills before adapting.
  3. Copy-paste trap — the source format is never the target format. Restructure the body, don't just translate headers.
  4. Missing domain detail — exact hex codes, pixel sizes, font weights, forbidden patterns ARE the skill. Stripping them destroys the value.
  5. Overlap blind spot — always check existing skills before adding. Two skills doing the same thing is worse than one.
  6. Reverse-sync blind spot (Layer 2) — after publishing, you keep improving locally. Without manifest tracking, the repo copy silently goes stale. Always record push dates.
  7. "Keep ours" is valid — not every upstream diff requires a merge. When your version is a superset, record the decision and move on.
  8. Merge subagents need explicit preserve lists — without listing what must NOT be removed, a merge subagent may overwrite everything with upstream.
  9. Engine-tracking skills need different sync — compare installed version vs latest release, not SKILL.md content. A stale binary breaks the skill even if the SKILL.md is current.
  10. Silent auth dependency — a backend that "just works" on a developer's desktop may require cookies, QR login, or a browser extension impossible on a server. Surface the auth boundary explicitly.
  11. Atomic skills principle — keep skills atomic (one capability per skill). The agent chains skills at runtime, not at design time.
  12. Mutual exclusivity in portable repos — each skill must be self-contained. Don't extract shared modules; duplication is the price of independence.
  13. Sediment — a skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces.
  14. No-op prose — "be careful," "be thorough" rarely change behavior. Replace with checkable completion criteria.
  1. 浅层移植毫无价值 — 残留源术语、缺失触发词、未重构的技能毫无用处。始终完成完整适配流程。
  2. 技能膨胀 — 不要移植139个技能，仅保留35个有价值的。在适配前果断删除精简/指向型/重复/娱乐型技能。
  3. 复制粘贴陷阱 — 源格式绝非目标格式。重构正文，不要仅翻译标题。
  4. 缺失领域细节 — 精确的十六进制代码、像素尺寸、字体权重、禁用模式是技能的核心价值。删除这些会破坏技能价值。
  5. 重叠盲区 — 添加新技能前务必检查现有技能。两个技能做同一件事比一个技能更糟。
  6. 反向同步盲区（层级2） — 发布后持续在本地优化。若无Manifest跟踪，仓库副本会默默过时。始终记录推送日期。
  7. “保留本地版本”是合理选择 — 并非所有上游差异都需要合并。当你的版本是超集时，记录决策并继续。
  8. 合并子Agent需要明确保留列表 — 若未列出必须保留的内容，合并子Agent可能会用上游版本覆盖所有内容。
  9. 引擎跟踪技能需要特殊同步方式 — 对比已安装版本与最新发布版本，而非SKILL.md内容。即使SKILL.md是最新的，过时的二进制文件仍会导致技能失效。
  10. 隐性认证依赖 — 在开发者桌面“正常工作”的后端，可能需要Cookie、扫码登录或服务器无法使用的浏览器扩展。需明确说明认证边界。
  11. 原子技能原则 — 保持技能原子性（每个技能对应一个能力）。Agent在运行时链式调用技能，而非在设计时整合。
  12. 可移植仓库的互斥性 — 每个技能必须独立完整。不要提取共享模块；重复是独立性的代价。
  13. 内容沉淀 — 技能应随时间变得更简短、更精准。添加规则时，删除被替代的旧表述。
  14. 无效描述 — “小心”、“彻底”等表述几乎不会改变行为。替换为可检查的完成标准。

Verification Checklist

验证清单

  • Overlap checked — no existing skill covers the same capability
  • Frontmatter valid — starts with 
    ---
    , closes with 
    \n---\n
    , parses as YAML
  • name
    (≤64 chars, lowercase+hyphens) and 
    description
    (≤1024 chars) present
  • Structure: Overview → When to Use → body → Pitfalls → Verification
  • Each step has a checkable completion criterion
  • No no-op prose or duplicated rules
  • Total file ≤100k chars (aim for 8–15k)
  • Bulky reference material in linked 
    references/*.md
    files
  • Scripts are deterministic, pure stdlib where possible
  • UPSTREAM_MANIFEST.md updated if skill has external provenance
  • PORT_NOTES.md created for complex adaptations
  • Jargon check passed — no upstream-specific terms in adapted files
  • Published version debranded + generalized + tested
  • Cron job configured for monthly drift detection
  • tests/test_upstream_check.py
    (this skill's own suite) passes — run 
    python3 -m pytest tests/ -q
    from the skill directory
  • 已检查重叠性——无现有技能覆盖相同能力
  • 前置元数据有效——以
    ---
    开头，以
    \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