sync-notes Skill

Sync the local notes directory ($CLOUD_NOTES_PATH) with a Cloudflare R2 bucket through an end-to-end encrypted rclone crypt remote. The skill is a thin orchestrator over a single bash entry point at scripts/sync.sh; the LLM's job is to translate the user's natural-language intent into the right subcommand.

Trigger

Activate only when the user message starts with /sync-notes (with or without trailing arguments). Examples:

How to interpret natural language

After stripping the /sync-notes prefix, classify the remainder:

1. Empty → run bisync (default bidirectional sync).
2. Contains a recognised keyword:
   • setup, 配置, wizard → setup
   • init, 初始化, baseline → init
   • status, 状态, 信息 → status
3. Mentions download intent (下载, 拉, pull, download, get, 取回):
   • Extract the target token(s) and convert to a glob (see "Glob rules" below).
   • Run sync.sh download '\x3Cglob>'.
4. Mentions upload intent (上传, 推, push, upload, send):
   • Same as above with sync.sh upload '\x3Cglob>'.
5. Otherwise: ask the user to clarify; do not guess.

Glob rules

Globs are passed verbatim to rclone as --include filters and apply to plain (decrypted) paths.

• A bare keyword such as welcome becomes **welcome** (matches anywhere in path).
• A directory name like ideas becomes ideas/**.
• Paths already containing wildcards (*, ?, [) are passed through unchanged.
• Filenames without extension default to matching \x3Cname> and \x3Cname>.md; combine with ** if unsure. When in doubt, run sync.sh download '\x3Cglob>' --dry-run first.

Workflow contract

1. First run ever: the script refuses bisync until a baseline exists. Tell the user to run /sync-notes init after confirming both sides are in the desired starting state.
2. Backups: before any write-side operation (bisync, download, init), the local notes directory is mirrored to backups/latest/ (single rolling copy, previous one is replaced).
3. Conflicts: bisync runs with conflict markers. After every run the script scans for *.conflict* files; if any are found the script exits non-zero and lists them. Surface this list to the user verbatim and ask which side to keep—do not auto-resolve.
4. Logs: every invocation appends to logs/sync.log and emits a per-run file logs/\x3CUTC-timestamp>.log for the rclone output.

Filesystem layout

skills/sync-notes/
├── SKILL.md                  # this file
├── README.md                 # short user-facing notes (optional)
├── config/
│   ├── rclone.conf           # active rclone config (created by setup, gitignored)
│   ├── rclone.conf.example   # template
│   ├── .env                  # non-rclone settings (created by setup, gitignored)
│   └── .env.example          # template
├── scripts/
│   ├── sync.sh               # main entry point (dispatcher)
│   └── setup.sh              # interactive configuration wizard
├── state/
│   └── bisync/               # rclone bisync workdir (listings + lockfiles)
├── logs/                     # rolling logs
├── backups/
│   └── latest/               # most recent local snapshot (single copy)
└── .gitignore

scripts/sync.sh derives every path from its own location ($(dirname "$0")/..); no absolute paths are hard-coded.

Required environment

The script aborts early with a clear message if CLOUD_NOTES_PATH is unset, missing, or not a directory.

Configuration files

config/rclone.conf

Native rclone format with two remotes:

[r2-raw]
type = s3
provider = Cloudflare
access_key_id = \x3CACCESS_KEY_ID>
secret_access_key = \x3CSECRET_ACCESS_KEY>
endpoint = https://\x3CACCOUNT_ID>.r2.cloudflarestorage.com
acl = private

[notes]
type = crypt
remote = r2-raw:\x3CBUCKET>/\x3COPTIONAL_PREFIX>
filename_encryption = standard
directory_name_encryption = true
password = \x3COBSCURED>
password2 = \x3COBSCURED>

config/.env

Non-rclone settings consumed by sync.sh:

# Name of the crypt remote in rclone.conf
RCLONE_REMOTE=notes
# Number of local backup snapshots to retain
BACKUP_KEEP=1
# Extra rclone flags (optional)
RCLONE_EXTRA_FLAGS="--transfers=4 --checkers=8"

.example versions ship with the skill; the wizard fills in the real values.

Subcommands implemented by sync.sh

Safety rules for the LLM

• Never write secrets into chat. If the user pastes secrets, immediately move them into config/rclone.conf / config/.env and remove from any visible context.
• Never invoke rclone with --config pointing somewhere outside this skill.
• Never run bisync if status reports unresolved conflicts; ask first.
• When download/upload glob match count is ambiguous, run with --dry-run first and show the list of matches.
• Backups are single-copy; if you are about to do something risky (large delete, schema change), copy backups/latest/ to backups/manual-\x3CUTC>/ manually before proceeding and tell the user.

First-time onboarding (what to tell the user)

1. /sync-notes setup           # fill in R2 + crypt creds
2. export CLOUD_NOTES_PATH=...  # point at the local notes dir
3. /sync-notes init             # establish the bisync baseline
4. /sync-notes                  # routine bidirectional sync