agentleFS
craigcossairtcraigcossairt/trellis/.claude/skills/trellis-sync/SKILL.md

trellis-sync

Skill5 starsChanged 11 days agoMITView on GitHub

Check this project against the template it was made from, show what changed upstream, and apply only what the user picks. Use when asked to "check for template updates", "sync with trellis", "is my template copy out of date", "pull in upstream template changes", "what changed in the template".

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If there is no .trellis/manifest, this copy predates the sync mechanism or was not made from the template.

    line 32
  2. Very specific:

    If a file needs a matching change elsewhere - a skill and its retained adapter routers, a hook and its settings.json entry - take both or …

    line 79
  3. Distinctive:

    If the user declined everything, nothing is written - not the manifest, not the version.

    line 99

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Sync a copy against the template it came from

A copy made from a GitHub template has no git relationship to the template, so there is no "git pull" for it. This procedure closes that gap: it reports what upstream changed, and applies only what the user chooses.

The rule that matters

You do not classify anything yourself. bin/trellis-sync.sh decides which bucket each file is in. Read its output and act on that. If you eyeball the files and form your own opinion, you will eventually tell someone a file is safe to overwrite when they spent an afternoon editing it.

1. Run the check

bash bin/trellis-sync.sh --porcelain

Each line is <bucket>\t<path>. Exit codes: 0 nothing to take, 1 there is something, 2 could not tell.

Exit 2 is not "you are up to date." It means the check did not run - no manifest, an unreachable upstream, an empty response. Report what it said and stop. Never summarise a failed check as good news.

If there is no .trellis/manifest, this copy predates the sync mechanism or was not made from the template. Say so. Do not offer to generate one from the current tree: a manifest built from an already-modified copy records your edits as if upstream had shipped them, and every future sync inherits that lie.

2. Read the buckets back to the user

BucketMeansDefault
applyUpstream changed it; this copy has notOffer to take it
addedUpstream has a new file this copy lacksOffer to take it
conflictChanged upstream and hereAsk. Never auto-apply
removedUpstream deleted it; this copy still has itAsk. Deleting is theirs to choose
deletedDeleted here; upstream still ships itMention once. Assume deliberate
localonlyChanged here, unchanged upstreamNothing to do. Do not list these individually

Lead with apply and added, because those are the cheap wins. Summarise localonly as a count. A report where everything looks urgent gets skimmed.

3. Apply what they pick

You do not fetch or write files yourself. One command does it:

bash bin/trellis-sync.sh --apply <path> [--apply <path> ...]

It resolves the upstream to a single immutable commit, takes the bytes for each path from that same commit, checks each one against its hash in the upstream manifest, and only then moves it into place. A file that fails any of that is not written and the run exits 2.

The earlier version of this section told you to run gh api "repos/<upstream>/contents/<path>" ... > "<path>" by hand. Do not go back to it, and do not reach for it when the script is inconvenient. It was wrong twice over. That URL is the default branch, while the buckets above are computed from the release manifest, so the bytes written were not the bytes that had been classified. And > truncates the destination before the fetch runs, so a failed fetch left an empty file where the adopter's file had been. That is measured, not theoretical: 42 bytes to 0.

Rules that still need you:

  • Show the diff before applying, for every file, including apply. "Safe to take" means nobody edited it here, not that they wanted the change.
  • Never apply a conflict file without the user having seen both versions. Taking an update is a whole-file write. There is no merge.
  • If a file needs a matching change elsewhere - a skill and its retained adapter routers, a hook and its settings.json entry - take both or neither.
  • removed is not applied by this tool. Upstream deleting a file is not the same as you wanting it gone; delete it yourself if you agree.

4. Recording happens automatically. Do not "regenerate the manifest"

--apply rewrites only the manifest lines for the files it actually took. Everything else is left exactly as it was, which is what makes a declined update show up again next time instead of disappearing.

Never run bin/trellis-manifest.sh --write in a copy. It hashes every tracked file, so it records your work as though the template had shipped it. Measured on a fixture: a template file the adopter had edited and declined went from localonly to apply - "SAFE TO TAKE" - on the very next run, and their own src/app.ts appeared under "REMOVED UPSTREAM - decide whether to keep". The command now refuses to run outside the template, but the reason matters more than the guard: the manifest records what the TEMPLATE shipped, and the moment it records anything else, every later sync inherits that.

If the user declined everything, nothing is written - not the manifest, not the version. Declining is not syncing, and recording it as one would hide those same updates next time.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.