sg

← Writing

A Sync Script Should Delete Only What It Wrote

· ai · reliability

agentsync is a small open-source tool I wrote that generates the config files for AI coding agents. When each tool kept its own hand-written copy of the prompts, the copies drifted apart, so agentsync keeps one source. That source includes skills: folders of instructions an agent can load when it needs them.

You edit agents/ and run a sync script. The script writes .claude/, .codex/, .opencode/, .agents/skills/, and optionally .github/ for Copilot. Until version 0.2.2, every sync started by emptying the folders it was about to write into. Those folders aren't only agentsync's, so anything else in them went too. Version 0.2.2 changed the rule: agentsync now writes down what it wrote, and deletes only what is on that list.

Emptying a folder assumes you own it#

The old approach was simple on purpose. In the script for Claude Code, the skills step was four lines: empty the output folder, then copy the source in. Here they are, next to the one line that replaced them:

diff · bash
-rm -rf "$TARGET/skills/"*
-if [[ -d "$SKILLS_SRC" ]]; then
-    cp -r "$SKILLS_SRC/"* "$TARGET/skills/"
-fi
+sync_skill_dirs_verbatim "$SKILLS_SRC" "$TARGET/skills"

Because it deleted everything before copying, the output could never go out of date, and a skill you deleted from the source was gone from the output on the next run. The scripts for Codex, OpenCode, and Copilot worked the same way. The README agentsync puts in agents/ says it plainly: never edit .claude/ by hand, because every sync rewrites it.

That only works if agentsync is the only thing writing there, and it isn't. .claude/skills/ is where Claude Code looks for skills, so your own skills live there too, along with files that other tools generate. Deleting everything treats all of it as old agentsync output, and a skill you wrote yourself in that folder would be gone after the next sync.

Write down what you wrote#

The line that replaced those four still deletes and copies, but it checks a list first. The list is a hidden file, .agentsync-manifest, in each skills, agents, and rules folder that agentsync writes to. It holds everything agentsync put there, one name per line: a skill folder, an agent file, or a rule file. On the next sync, agentsync reads that list and deletes a name only if it is on the list and no longer in the source.

This loop does the deleting, before anything is copied. owned1 is the list of names in the source on this run:

bash
if [[ -f "$manifest" ]]; then
    local prev name keep
    while IFS= read -r prev; do
        [[ -n "$prev" ]] || continue
        keep=0
        for name in ${owned[@]+"${owned[@]}"}; do
            [[ "$name" == "$prev" ]] && { keep=1; break; }
        done
        [[ $keep -eq 0 ]] && rm -rf "${target:?}/$prev"
    done < "$manifest"
fi

Then agentsync writes the new list to the manifest and copies the source's entries in. Every name in the folder falls into one of four cases:

On manifestIn sourceAfter sync
yesyesRecopied
yesnoDeleted
nonoLeft alone
noyesAdded to the manifest, then replaced

The "Left alone" row is the one that protects your files, as this blog shows. Its writing skills live in a top-level skills/ folder, with symlinks (file shortcuts) to them in .claude/skills/. The manifest there lists three names: draft-post, portfolio-ground-truth, and shape-post. The three symlinks aren't on it, so they were still there after the last sync.

The last row is the risky one. If you have a skill folder with the same name as one in the source, agentsync doesn't merge the two: it deletes your folder and copies the source's version in its place. An agent or rule file with the same name gets overwritten the same way. From then on, agentsync owns that name.

agentsync also writes into a file it shares with you, .gitignore. There the record of what it wrote is a pair of marker lines instead of a list: agentsync writes its lines between # >>> agentsync >>> and # <<< agentsync <<<, and later runs replace only that block. The rest of the file is yours.

Good manners only work one way#

The manifest makes agentsync a polite neighbor, but it does nothing about rude ones. If another tool shares the folder and still empties it before it writes, that tool's next run deletes agentsync's skills. agentsync can't stop that. It can notice, but not from the sync script.

The noticing happens in agentsync's own skill. An agent follows that skill when it sets up a project, and again when it audits the project later. Both times, it looks for files with another tool's "generated by" or "do not edit" banner, and if it finds one, it reports the shared folder and the risk so you can decide whether to keep sharing it.

So the fix holds from one side only. Whether the rest of a shared folder survives depends on every other tool there also deleting only what it wrote.

Footnotes

  1. The odd ${owned[@]+...} form is there for bash 3.2. Under set -u, that version treats an empty array as an unset variable and stops. ↩