dby-update

dby-update: reconcile this duck to the latest

First --dry-run produce a list, and after the user approves --yes; no confirmations beyond the list are made. Shell permissions are decided by the user in the host permission window.

What this skill does is "reconciliation," not "updating"

Make this machine's set of this-duck skills equalthe upstream current full set:

archiveones upstream has delisted
installnewly added ones
refreshones whose content hash lags behind the upstream current version,and ones whose content is the current version but are missing one placement; ones missing neither are left untouched

🔴 "The content is the current version" does not equal "already in place." The host reads skills according toits own directory—Claude Code only reads .claude/skills, and when a package only lands in .agents/skills itdoes not exist at all. The reconciliation criterion is "content and placement": if any managed install directory on this machine is missing a placement, the package is reinstalled once to fill it in, listed separately with 🩹 in the plan.

When this machine already matches upstream, the conclusion isno action needed, and not a single package is re-downloaded; to reinstall a broken package, use --force-refresh。

⚠️ Do not use npx skills update: packages that upstream has renamed / delisted will besilently skipped and remain on this machine forever, and it cannot see project-level installs either.

How to tell "whether this package was published by this duck"

The criterion is slug × content hash, regardless of which source it was originally installed from. Upstream index.json one entry per slug:status, historical hash closed set, each version's semver + changelog:

Status	Criterion	Action
Current version	hash = index current version	keep,do not refresh(unless `--force-refresh`）
our old version	hash hits some historical version in the closed set	refresh; only archive / migrate if the index `status` is retired/renamed/merged
User has modified it	when there is `.dby/origin.json` the hash ≠ the record at install time; without origin, the hash hits nothing	🔴 skip and list in the report, without changing a single character, not even a refresh is given
Other people's	the slug is not in the index at all	leave alone
Already pinned	user `--pin` has pinned	do not refresh, do not archive, do not migrate; list separately in the pre-check with the reason

→ origin / lock / pin, legacy fallback, Gitee mirror:references/index-and-lock.md。

Deletions are always made as "archives"

packages to be delistedMove <scope>/.doubaoya/archive/<时间戳>/, do not rm, keep a copy in the same directory manifest.json State where each package originally was and how to move it back.

Three accompanying points: after archiving, the script prints a pasteablerestore command(it works immediately after moving back; the skills CLI record requires a reinstall before it recognizes it); the archive directory is at .doubaoya/.gitignore write * self-ignore,do not modify the user's .gitignore； 🔴 Packages tracked by git are never archived(equivalent to deleting tracked files); the script skips them and lists them in a separate column for the user to decide.

Rename migration (renames.json)

→ Upstream occasionallyrenamesa package (rather than simply removing it), in which case the local data in the old directory (such as dby-publish the config.jsonofRead references/rename-migration.mdwhen rename migration needs to be handled, otherwise do not read it. Three key points: rename = entries in the index with status: renamed/merged ; the order is fixed asinstall new package → move local data → archive old directoryand each is independent;do not overwrite when the new directory already has a file with the same name, only report "conflict not overwritten" and give the old file's path in the archive directory—this sentence must be relayed to the user verbatim。

Execution steps

1. Find the reconciliation script

Search in order for the first one that exists:

~/.claude/skills/dby-update/scripts/reconcile.mjs
~/.agents/skills/dby-update/scripts/reconcile.mjs
./.claude/skills/dby-update/scripts/reconcile.mjs
./.agents/skills/dby-update/scripts/reconcile.mjs

Not found = not installed on this machine or an old version. 🔴 Do not install automatically: report "reconciliation script not installed on this machine", give the user the following command,run it after confirmation, and after it finishessearch again：

npx -y skills add zizhanovo/doubaoya-community -g -s '*' -a claude-code universal -y

🔴 Zero output and exit code 0 ≠ nothing to do; it means the old script, when invoked via a symlink (.claude/skills/…), does not run a single step: first rerun with the real path from .agents that entry; if it still behaves the same, reinstall using the install command above (run after confirmation), then search for the path again.

2. Look at the list first (🔴 explicitly provide scope, do not rely on auto guessing)

node <上一步找到的路径> --dry-run --scope global              # 当初带 -g 装的（最常见）
node <上一步找到的路径> --dry-run --scope project --project-dir <项目目录>

When scope is guessed wrong, the script prints a ⚠️ warning; if you see it, confirm the scope first; if unsure where it is installed, look at both scopes. Both scopes printing "not a single Doubao skill" = not installed on this machine; go back to step 1 and ask the user first, and do not treat "install the whole repo" as reconciliation.

It fetches the upstream index online and printswhich to archive, which to install, which to refresh (line by line slug 旧版 → 新版 changelog; marked auto are placeholder text), and which are left untouched because the user modified them / pinned them, without changing a single character. Relay this listto the user verbatim—especially the names and changelogs of "to archive", "to refresh", and "user-modified" (refresh is an overwrite install, so what is confirmed must be the specific list).

🔴 Conclusions must not exceed the evidence. When the upstream directory / index was not verified in this run, the script degrades but does not abort (does not archive, or falls back to the old three files), the conclusion must truthfully say it degraded, do not say "completely consistent". GitHub rate limiting automatically switches to the Gitee mirror with the same tag;mirrorMismatch is what truly means not fully pushed, use dby-feedback to report to the maintainer; the mirror is new but that version already exists on GitHub = just the cache not refreshed— Tell the user "it was just released; rerun in a few minutes to get the new version"; do not tell them to contact the maintainer. Field and criteria details → references/index-and-lock.md。

🧩 Old-version leftover copy (agent/skills/) handling → references/edge-cases.md。

3. After confirmation, execute

only after the user has seen the checklist and approved it (keep the scope parameter the same as given in the previous step）：

node <路径> --yes --scope <上一步用的那个> [--project-dir <目录>]

The script completes this itself: archive → fetch the full set → review → self-check, then prints a result and tells the user where the archive is.

🛡 Project scope refresh/addition uses "side-install → verify → atomic switch" with automatic rollback on failure; global scope has no such guarantee → references/staged-install.md。

Exit codes：0 all passed;3 reconciliation is done but a self-check item failed;1 user canceled;2 confirmation is needed but the current terminal is not interactive;4 error.

📝 The skills-lock.json in the project will be changed too; this is expected; if the user asks what git status added, explain then; do not bring it up proactively.

⚠️ What to do if the run hangs at "pulling upstream"; whether the list includes dby-update and whether to rerun it yourself → same as above references/edge-cases.md。

🏷 Pin the installation source to index.json top-level ref; if the field is missing, install from main and prompt "not pinned". Release tagging → references/release-ref.md。

4. Reply to the user (understandable by ordinary people)

🔴 The user is not an engineer. Say only three things:one sentence for the result → what changed this time → next step. Paths, hashes, refs, scope, .agents/skills、skills-lock.json, API keys, health checks—when everything is normal, do not mention any of them; only say where it is stuck and what to do when there is a problem. Use the Chinese name in the script parentheses for the package name, and put the slug in parentheses.

🔴 Exception:--json top-level notes[] all prompts inmust be relayed

更新好了。这次更新了 2 个：
- 公众号写作与复盘（dby-write）1.9.0 → 1.9.1：新增变更说明字段
- 都爆鸭 Skill 自更新（dby-update）3.3.1 → 3.4.3：隔多版更新时列出中间每一版的说明
    · 3.4.2 …（中间各版照抄脚本）
下架归档了 1 个：xxx。要恢复的话告诉我一声。
你自己改过的 1 个没动：yyy。
新开一个对话就能用上新版。

, translated into plain language—the mute list only covers technical details when "everything is normal", not these kinds of degradation prompts that say "the run finished but with compromises". references/index-and-lock.md）。
many versions behind → list at most 8 intermediate versions, collapse any beyond that, and simply relay what the script says (details →no updates → "Everything is up to date; no update needed." + one line with each package version (the script's line "Version: …").
Do not add "refreshed N" yourself. git rmOne sentence each for "pinned", "tracked by git and unchanged", and "git cannot determine, skipped"; do not mix them up: for the former the user should
, for the latter fix git first and rerun.
🩹 "Missing placement" → one sentence: "The content is up to date; it just filled in one installation location."
Archive → say where it was placed and that you can restore if they say so (paste the restore command only if the user asks).
Self-check ❌ → say which step it is stuck at (not installed / key not configured / cannot connect to service) + the method given by the script. .dby/origin.jsonAsk about package version → read its skills-lock.json。

Common parameters

Parameter	Purpose
`--dry-run`	Read the checklist only; never execute
`--yes`	Skip confirmation and execute directly (use only after the user has already seen the checklist）
`--force-refresh`	Re-download even packages that "are already the current version and fully placed" (leave this for "the package is broken and I want to reinstall")
`--verbose`	List names together even for "someone else's" and "user-modified" packages
`--scope auto\|global\|project`	🔴 Always specify explicitly every time. By default `auto` is guessed from cwd; if guessed wrong it silently becomes a "whole-repo reinstall". If it was originally installed with `-g` , it is `global`
`--project-dir <目录>`	Specify when the project-level install is in another directory
`--json`	Machine-readable output
`--self-check`	The offline self-check script itself (no network)
`--pin <slug> [--reason <文>]` / `--unpin <slug>`	Pin / unpin a package (no network, only modifies `<scope>/.dby/lock.json`); once pinned, reconciliation skips it. When the user says "don't update this package", use this
`--help` / `-h`	Show usage (no network, doesn't touch any install directory)

Boundaries

Only touches packages published by this duck(the criterion is the three-state table above); packages from others or modified by the user are not touched at all, not even one character.
🔴 Packages for which git detection fails or cannot be determined are likewise conservatively skipped; the script puts them and "tracked by git"in two columnsand prints them out, with different handling.
Don't touch the user's local data / config（dby-publish 's config.json, creative DNA, covers / drafts and other outputs)——reconciliation only covers version-managed files in the skill directory.
Don't create background tasks, scheduled tasks, or Agent Hooks.
The user only asks "what updates are there / what version is it now / should I update" → Answer first, don't execute（--dry-run is exactly for answering this). Only run step 3 when actual syncing is explicitly requested.
Only want to update oneGlobalskill：npx -y skills update <skill 名> -g, only touch the one named (no reconciliation; it can't see project-level installs, so still use this script).