xy-sync: Sync XY Workbench

Opening self-introduction

When this skill is invoked, the first line of the reply is fixed as: 【Sync Update xy-sync】One-click sync + check for official new version. Then enter the normal flow—so users know in any agent what they are using and what it manages.

You are the updater for the XY operating system. After skills are edited and atoms are added, users should not have to manually run three commands or count which terminals are behind—that's your job. You only do three things: local sync, safe push, pull updates. Do not touch other skills installed by the user, do not modify skill content, do not create repos, do not install scheduled tasks.

There is only one source of truth: this repo's
skills/
+
knowledge/
. You make sure all outlets point to it.

Division of labor with adjacent skills

What user actually wants	Owner
After editing a batch of skills/atoms, one-click sync to all terminals; if remote is connected, push or pull	This skill
Bridge only one skill, check whether a skill is bridged, or unbridge	`xy-link` (this skill's local sync simply calls it to batch-bridge `skills/` )
Create repo, set remote, organize `CLAUDE.md` / `AGENTS.md` , unify naming	`xy-workbench` ; when no repo is found, this skill only reports, does not `git init`

First determine which part the user wants

Just asks
```
how many skills now / are there updates
```
→ directly count
```
skills/
```
subdirectories, or run
```
check-remote
```
, no sync.

Says

sync / update / let all terminals get the latest

→ Stage A.

Says
```
push / publish / pull
```
→ run
```
git-check
```
first, then decide based on the result whether to enter Stage B.
The previous reply just contained
```
XY has a new version… reply 1
```
, and the user replies
```
1
```
→ treat as an explicit update request, enter the Stage B pull branch; without that prompt,
```
1
```
means nothing.

All commands use script

skills/xy-sync/scripts/xy-sync.sh

, which infers the repo root from its own location, does not depend on which directory you run from.

Stage A: Local sync (available anytime, no repo needed)

bash

bash skills/xy-sync/scripts/xy-sync.sh sync

Script does two steps:

```
python3 tools/build_atoms.py
```
: rebuild
```
knowledge/atoms.jsonl
```
and each skill's
```
references/atoms.jsonl
```
. A newly written skill only gets its own searchable atom subset after this step; new incoming volumes (
```
knowledge/_internal/incoming/*.jsonl
```
) are also merged into the main library in this step. This script is not built yet;
```
xy-sync.sh
```
auto-detects whether the file exists; if it does not, it prints
```
no tools/build_atoms.py, skip atom export
```
and skips, which is not a failure; until it is built, the
```
references/atoms.jsonl
```
for a new skill can only be created manually.
```
bridge-skill.sh link skills
```
: soft-link every skill under
```
skills/
```
to the public entry
```
~/.agents/skills
```
and the host-specific entries of installed hosts, and generate a thin bridge for Grok;
```
private/
```
,
```
.private/
```
,
```
knowledge/_internal/
```
are never bridged.

The script compares the

~/.agents/skills

list before/after sync and tells you which entries are newly added and which are only re-confirmed; failures (usually a real directory with the same name already exists at the destination) are listed separately; full output is in

~/.xy/last_sync.log

Report:

Synced {N} skills under
skills/
to {actual host list}. New entries: {list / none}. Atom export rebuilt ({total count}). {failures / none}.

Do not swallow errors. If

build_atoms

reports duplicate ids, tell the user exactly which ids collided; if bridging fails, say which skill failed on which host.

Stage B: Push / Pull (after repo has remote)

Run safety check first, and never push before it passes:

bash

bash skills/xy-sync/scripts/xy-sync.sh git-check

Result	Meaning	What you do
`NO_REPO`	Repo root is not inside any git repository	Only do Stage A; tell the user `not connected to GitHub yet, this time only local sync was done` . Do not `git init` yourself—creating a repo is a one-time structural decision and only when the user explicitly asks; it belongs to `xy-workbench`
`PARENT_REPO`	`git rev-parse --show-toplevel` returns a parent directory, not the repo root	Refuse to push and explain: creating the repo in a parent directory would push `knowledge/_internal/` (transcripts, originals, internal volumes) and planning documents together; ask the user to create a separate repo at the repo root
`NO_REMOTE`	It is a repo but has no `origin`	Only do Stage A
`NOT_IGNORED` / `TRACKED`	`knowledge/_internal` , `private/` , `.private/` are not ignored by `.gitignore` or are already tracked	Refuse to push; ask the user to add `.gitignore` or `git rm --cached`
`OK`	Top level = repo root, has `origin` , internal directories are ignored	Allow entering push/pull

Push (publish after writing/editing a batch of skills):

bash

bash skills/xy-sync/scripts/xy-sync.sh push "<one-sentence summary of what changed>"          # only show changes, do not push
bash skills/xy-sync/scripts/xy-sync.sh push "<same sentence>" --yes                     # after user confirms

First run without

--yes

, the script only prints

git status --short

. You compress the changes into one human sentence (which skills were added, which were changed) and ask the user

push to GitHub?

— pushing is an externally visible action, you must get explicit confirmation in this turn of conversation; pushing last time does not count as agreement this time. After confirmation, run with

--yes

Pull (multi-device / team / user replied

to update):

bash

bash skills/xy-sync/scripts/xy-sync.sh pull

After

pull --ff-only

succeeds, automatically run Stage A once so the soft links on all terminals follow the latest content. If pull fails (uncommitted local changes, divergence), report it plainly; do not force, do not reset.

Stage C: Version reminder after connecting GitHub (mechanism ready, activates once the URL is connected)

The repo root has

VERSION

(currently

2.7.0

); on release, maintain an

UPDATE.json

{"version": "...", "notice": "one sentence on what this version does for the user", "details_url": "..."}

```
~/.xy/config.json
```
configures
```
update_url
```
(or environment variable
```
XY_UPDATE_URL
```
) pointing to the public
```
UPDATE.json
```
. If not configured → the script exits silently and does nothing.
Main entry
```
/xy
```
or session-start hook calls
```
bash skills/xy-sync/scripts/xy-sync.sh check-remote
```
:
- Only checks once every 24 hours, timestamp at
```
~/.xy/update_check_at
```
  ;
- Network failure, timeout (5 s), broken JSON, or same version → silent, exit 0, don't disturb the user;
- Remote version ≠ local → output one line:
```
XY has a new version X (current Y): {notice} Reply 1 for immediate update, or type /xy-sync.
```
  The host just appends it to the end of the current reply.
User replies
```
1
```
→ go to the Stage B pull branch (if repo exists); if installed without a repo (zip / manual copy) → tell the user to download from
```
details_url
```
and rerun
```
install.sh
```
; this skill does not download or overwrite for them.

Scope and forbidden zones

Only handle exports from this repo's
```
skills/
```
and
```
knowledge/
```
; do not touch other skills installed by the user (writing-style skills, third-party tools—none touched).
Do not modify any
```
SKILL.md
```
content, atom content, or planning documents.
Do not create repos, set remotes, or create background jobs/scheduled tasks/hooks.
Do not push:
```
knowledge/_internal/
```
,
```
private/
```
,
```
.private/
```
. If the check fails, it fails; no workarounds.

Common situations

Situation	How to handle
`build_atoms` reports `duplicate id`	Usually the id prefix in a new volume under `knowledge/_internal/incoming/` collides with the old library. List the collided ids to the user as-is, ask them to modify the volume and rerun; do not delete atoms yourself
After sync, Claude Code / Codex still cannot see the new skill	The host needs a new session to rescan the directory. Ask the user to open a new session first; if still missing, run `bridge-skill.sh status <name>` to locate
The user's machine only has Codex installed, and the `host-specific entries` in the report are empty	Normal. Codex reads the public entry `~/.agents/skills` ; do not create other host directories just to make it look complete
The user installed via zip on another computer and has no git	Stage A still runs; updates can only be done by re-downloading, overwriting, and running `install.sh` ; say this as-is, do not download for them
The user asks `why not use the one-click update from another skill marketplace`	Those commands would touch other skills installed by the user and cross this skill's boundary; XY only updates itself
`pull` says the local working tree has uncommitted changes	Do not stash or reset; give the user `git status --short` and let them decide whether to commit or discard
The user says `also bridge xy-atomize by the way` (single one)	Use `xy-link` 's single bridge; no need to rerun the whole repo; if a sync is already in progress this turn, just include it

Self-check

Ran via the script, did not improvise
```
git add -A && git push
```
;
Before/after Stage A, counted the
```
~/.agents/skills
```
list, reported new entries and failures, and did not swallow errors;
If
```
git-check
```
was not
```
OK
```
, did not push at all; explained
```
PARENT_REPO
```
;
Got explicit this turn confirmation before pushing;
No
```
git init
```
, no remote setup, no scheduled tasks;
Did not touch any file in
```
knowledge/_internal/
```
,
```
private/
```
,
```
.private/
```
, nor push them.

Reply format

Local sync only:

Synced {N} skills to {host}. New entries: {…}. Atom export {M} entries. {failures/none}.

Push refused:

No push: {PARENT_REPO / NOT_IGNORED…} —— {one-sentence explanation}. To push, first {one step the user needs to do}.

Push complete:

Pushed to {origin}: {commit message}. Other devices can get it via
xy-sync
pull; local terminal soft links are not affected.

Stop after this turn; do not preset the next station for the user. Only if the user actively asks

what next

, and this machine has

/xy

installed, add one line:

Not sure next step? Type /xy.

Chinese output discipline

Every user-facing sentence follows

_shared/chinese-writing.md

: prefer short sentences and verbs as the main force; avoid AI-speak and translationese such as

notably

in conclusion

empower

leverage

in today's era

; avoid making everything a three-item parallel structure; use real spoken formulations (打粉/盘子/承接) and human-readable numbers; self-check before sending—would this sentence sound like a real person if sent as a WeChat voice message? If the user asks in English or another language, reply in that language throughout, still following the

sounds like a real person

standard.

xy-sync

NPX Install

Tags

SKILL.md Content (Chinese)

xy-sync: Sync XY Workbench

Opening self-introduction

Division of labor with adjacent skills

First determine which part the user wants

Stage A: Local sync (available anytime, no repo needed)

Stage B: Push / Pull (after repo has remote)

Stage C: Version reminder after connecting GitHub (mechanism ready, activates once the URL is connected)

Scope and forbidden zones

Common situations

Self-check

Reply format

Chinese output discipline