SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsupstream-sync

upstream-sync

Deployment & operations

View repository

Updated 10-15 10:51

About this skill

Upstream-synced plugins

Some plugins are ported from external repositories and should be kept in sync with their upstream source. When asked to update one of these plugins, fetch the latest content from the upstream URL using gh api and apply any changes, then follow the standard marketplace update workflow in AGENTS.md.

Local sync targets are neutral kernels: plugin.toml, roles/, workflows/ with TOML sidecars, skills/, contracts/ and policies/. Host-specific mechanisms belong in adapters/; exports/ and root catalogs are generated. Upstream agents/ and commands/ paths describe that upstream's layout, not local source.

Nothing listed under "Deliberately not vendored" in AGENTS.md belongs in the table below. Those areas were removed and delegated on purpose; do not add rows for them on a future pass. The former obra/superpowers export row was retired with the VS Code extension and stays retired.

Default upstream-update strategy

When the user asks for "upstream updates" (or similar), this is the default workflow. Do not blindly overwrite local files - most syncs need targeted merging because local has legitimate customizations.

  1. Check all synced plugins in parallel. For each file in the sync table below, diff the upstream against the local version. Spawn Explore agents when there are many files to parallelize the diffing. Focus the reports on: which files differ, what changed, and whether the drift is intentional or worth pulling.

  1. Classify each file before touching it:

    • Clear win - new upstream file missing locally, or a bug/fact fix with no local conflict. Pull directly.
    • Minor refinement - small wording/metadata changes. Pull if no local frontmatter or content conflicts.
    • Hard merge - upstream rewrote a section we also evolved locally. Layer upstream changes onto local; do not overwrite.
    • Intentional drift (do not touch) - local namespace rewrites (upstream <their-plugin>: -> local <our-plugin>:), local polish (typo fixes, expanded triggers), style conventions (no dash-aside construct per AGENTS.md; no emojis in some plugins), local-only additions (custom presets, Ecosystem Integration sections), upstream dash-asides rewritten to sentences/parens/colons.

  2. Preserve these local customizations on every merge:

    • Source attribution lines at the top of files
    • Frontmatter: localized description (often multiline with >), tools, color, version, model
    • Plugin-specific style: no dash-aside construct (rewrite "X — Y — Z" / "X -- Y -- Z" / "X - Y - Z" asides into sentences, parens, or colons), no emojis in some plugins
    • Namespace replacements (upstream <their-plugin>:X -> local <our-plugin>:X)
    • Local-only sections (e.g., ## Ecosystem Integration blocks added during earlier syncs)

  3. For unresolved material choices, ask the user through the host's question mechanism. Reuse the accepted scope and existing decisions:

    • When upstream rewrote a section we also evolved (merge vs keep vs overwrite)
    • When upstream adds a feature that conflicts with local direction
    • When a file is flagged as "major drift"

  4. Apply targeted Edits, not Writes - prefer surgical edits that fix specific bugs (stale tool names, added items in a list) over replacing whole files. Only use Write for new files or when the entire file is being replaced.

  5. Keep imported behavior host-neutral. A kernel states ownership, isolated delivery, barriers and evidence requirements without naming native team or tool primitives. Translate upstream spawn/coordination instructions into those obligations and declared phase/dispatch metadata. Put a host-specific mechanism in that host's adapter only when supported by its binding and evidence. Run the host-vocabulary linter after team-related imports; replacing one Claude tool name with another in a kernel does not make it portable.

  6. Version bump and rebuild - bump each touched plugin's version in plugins/<name>/plugin.toml and metadata.version in .claude-plugin/marketplace.json. Rebuild every host with python scripts/daodan_build.py and regenerate the component/dependency reference with python scripts/sync_plugin_docs.py when a kernel changes; catalog entries and exports are generated, never hand-merged.

  7. Verify and commit - run python scripts/daodan_build.py --check, python scripts/sync_plugin_docs.py --check and the required repository gates before publication, check named consumers and bundled paths, then inspect git status / git diff --stat. If repository workflow skills changed, regenerate their native Codex adaptations with python scripts/sync_codex_instructions.py and check parity with --check. Commit kernels, regenerated exports/catalogs, documentation references and instruction copies together with a descriptive message like "Sync upstream updates for X and Y (vN.N.N)". Push to master under the task's publication authorization.

Plugin Upstream source Files to sync
codebase-xray (inspiration) gsd-build/get-shit-done - agents/gsd-codebase-mapper.md plugins/codebase-xray/workflows/analyze.md (patterns adopted, not direct copy)
react-development (react-best-practices) vercel-labs/agent-skills - skills/react-best-practices/ plugins/react-development/skills/react-best-practices/SKILL.md, plugins/react-development/skills/react-best-practices/references.md, plugins/react-development/skills/react-best-practices/rules/*.md
digital-marketing (domain-hunter) ReScienceLab/opc-skills - skills/domain-hunter/ plugins/digital-marketing/skills/domain-hunter/SKILL.md, plugins/digital-marketing/skills/domain-hunter/references/registrars.md, plugins/digital-marketing/skills/domain-hunter/references/spaceship-api.md, plugins/digital-marketing/skills/domain-hunter/examples/auto-video-editing-domain.md
docker (multi-stage-dockerfile) github/awesome-copilot - skills/multi-stage-dockerfile/SKILL.md plugins/docker/skills/multi-stage-dockerfile/SKILL.md
codebase-xray (semantic-interconnect-mapper) wshobson/agents - plugins/agent-orchestration/agents/context-manager.md (pattern cherry-picked, not a direct copy) plugins/codebase-xray/roles/semantic-interconnect-mapper.md. Owned by senior-review until marketplace 16.0.0.
typescript-development (mastering-typescript) SpillwaveSolutions/mastering-typescript-skill - mastering-typescript/ plugins/typescript-development/skills/mastering-typescript/SKILL.md, plugins/typescript-development/skills/mastering-typescript/references/*.md, plugins/typescript-development/skills/mastering-typescript/scripts/validate-setup.sh, plugins/typescript-development/skills/mastering-typescript/assets/tsconfig-template.json, plugins/typescript-development/skills/mastering-typescript/assets/eslint-template.js. Adaptation on sync: SKILL.md frontmatter is rewritten to local convention (keep only name and description; strip upstream version, category, triggers, author, license, tags). Description uses description: > multiline form with explicit TRIGGER WHEN / DO NOT TRIGGER WHEN routing, scoping this skill to enterprise/advanced TS work (advanced type system, JS-to-TS migration, toolchain bootstrap, Zod, deep React + TS, NestJS, LangChain.js) and routing routine TS/JS writes to typescript-development:typescript-write, React perf to react-development:review-react, and dead-code to typescript-development:knip. Without this rewrite the skill failed to auto-activate on its core scenarios because upstream's single-paragraph "Use when..." description loses the router race against typescript-write (added in v2.1.0). The local Source: ... attribution line at the top of SKILL.md and the body content are NOT subject to upstream-driven frontmatter changes on future syncs.
kotlin-development (full vendor, MIT) Jeffallan/claude-skills - skills/kotlin-specialist/ plugins/kotlin-development/skills/kotlin-specialist/SKILL.md, plugins/kotlin-development/skills/kotlin-specialist/references/{coroutines-flow,multiplatform-kmp,android-compose,ktor-server,dsl-idioms}.md. Adaptation on sync: strip upstream extra frontmatter fields (license, metadata.author, version, domain, triggers, role, scope, output-format, related-skills); keep only name and description in local frontmatter; rewrite upstream single-paragraph description into local description: > multiline form with TRIGGER WHEN / DO NOT TRIGGER WHEN. Add MIT attribution header comment immediately after the frontmatter on SKILL.md and at the top of every reference file. Drop the upstream [Documentation](https://jeffallan.github.io/...) link at the bottom of SKILL.md. Single-connector em-dashes ("X — Y") in code comments are preserved as-is (they are NOT bracketed asides).
project-knowledge (Karpathy principles, MIT) multica-ai/andrej-karpathy-skills: skills/karpathy-guidelines/SKILL.md Principles 1-4 retain upstream attribution in plugins/project-knowledge/skills/instructions-method/references/working-principles.md. Their sub-bullets and principle 5 are local. Creation uses the block when equivalent project guidance is absent; maintenance preserves equivalent guidance. Update the canonical reference and the instruction example together when their shared facts change; generated instruction files remain the target project's concern.

How to sync a plugin

The sync table above gives the upstream repo and the local target files. Single-file pattern:

gh api "repos/<owner>/<repo>/contents/<upstream-path>" --jq '.content' | base64 -d

For directories, list children first then iterate:

gh api "repos/<owner>/<repo>/contents/<dir>" --jq '.[].name' | while read f; do
  gh api "repos/<owner>/<repo>/contents/<dir>/$f" --jq '.content' | base64 -d
done

After fetching, compare with the local kernel file, preserve local additions (attribution headers, frontmatter conventions, namespace replacements, no-dash-aside style), then follow the version, rebuild, verification and authorized publication steps above.

Non-obvious per-plugin sync notes (read alongside the sync table):

  • domain-hunter: upstream Step 3 uses dedicated Twitter/Reddit Python scripts. Replace with WebSearch queries targeting site:x.com / site:reddit.com.

Sync notes from the 6.2.0 to 6.3.0 pass (2026-08-20), all applied with git merge-file against the pinned base rather than by overwriting:

  • The two references/*-tools.md changes are out of scope as always, and so is the upstream Hermes line in using-superpowers/SKILL.md: this port replaces the whole "Platform Adaptation" section with "How skills work here", so there is no list to add a harness to.
  • visual-companion.md's 6.3.0 change edits the Copilot CLI launch block. This port collapsed all five per-platform blocks into one, so the hunk has no target here and was skipped.
  • render-graphs.js was converted to ESM upstream, which is correct there ("type": "module" in the upstream package.json) and broken here: the export ships no package.json next to it, so .js is CommonJS and import would not parse. The two substantive 6.3.0 fixes (execFileSync instead of execSync, and probing dot -V instead of which dot, which is not a command on Windows) were taken; the require calls were kept, with a comment in the file saying why.
  • The upstream "Waiting on dispatched subagents" paragraph in subagent-driven-development/SKILL.md assumes detached children and a wait interface. VS Code's #agent/runSubagent returns only when the subagent finishes, so it was replaced with a paragraph stating that and keeping the useful half (do local work between dispatches).
  • The new "You Do Not Dispatch Subagents" section in the four *-prompt.md templates maps onto the sp-* agents, which all ship agents: []. The section was added in a shortened form that names the empty allowlist as the mechanical reason, rather than mirroring upstream's prose about a risk this platform already forecloses.
  • Two graphviz conflicts in subagent-driven-development/SKILL.md resolved in favor of upstream's node renames (Ask human partner which governs becomes Rule on the conflict, ledger the ruling) while keeping this port's fix-round wording, which says a fresh implementer is dispatched every round because VS Code cannot resume a returned subagent.
  • Jeffallan/claude-skills (kotlin): strip extra upstream frontmatter fields (license, metadata.author, version, domain, triggers, role, scope, output-format, related-skills). Drop the trailing [Documentation](https://jeffallan.github.io/...) link. Preserve single-connector em-dashes (X — Y) inside code comments; they are not bracketed asides.