sync-changes
Skill4 starsChanged 47 days agoMITView on GitHub
Use at the start of any editing session in this repo, and before delivering any change — pull the latest state before editing, never commit directly to main, and land work as a branch and a pull request. Use whenever asked to make, save, ship, or publish a change, or when starting a new task here.
- Commits and pushes
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- write-a-skillSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 54
If you are stale, rebase onto the live branch or start a fresh branch from it.
- Very specific: line 56
Never work directly on
main: Create or switch to a branch first, e.g. - Very specific: line 129
This section is about
ghin a shell — route 3 above: If you are opening the pull request through a platform control or an MCP tool, type … - Very specific: line 134
Never pass a multi-line body as a
--body "…"argument: Write it to a file and use --body-file: - Distinctive: line 165
The body must describe the change that was requested: Not the setup you did along the way, not a side effect you swept up.
≈ “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.
Files
Sync and deliver changes
This is a template: main is not guaranteed to be any given adopter's
production branch — that's a per-project decision, not something this repo
declares. On many projects it will be (this repo's own README documents
VERCEL_ENV disambiguating a production deploy from a preview one, which
only matters if main is what ships to production), but treat that as
unconfirmed until you know otherwise. Before your first commit in a
session, confirm which branch this project actually deploys from — ask
the operator, or check the hosting provider's project settings (e.g.
Vercel's Production Branch) — and treat that branch, not necessarily
main, as the one nothing gets pushed to directly. If you cannot confirm
it, assume the worst case (that the branch you're on ships live) rather
than the permissive one. Committing directly to the live branch publishes
to whoever is looking at the live site, with nobody having reviewed it
first. This repo's own CI (.github/workflows/ci.yml) runs
pnpm run checks on every pull request — the same command you run locally,
covering harness:check, content:check, catalog:check, gallery:check,
lint, test, typecheck, and build. That gate only fires on a PR, so a
direct push to any branch that skips the PR step skips it entirely. Run
pnpm run checks before you deliver: CI runs the identical script, so a
failure there is one you could have seen first.
The workflow
Pull before editing, and say what base you are on.
git fetch, then check that your branch point actually matches the live branch:git fetch origin git log --oneline -1 origin/main git merge-base --is-ancestor origin/main HEAD && echo "up to date" || echo "STALE"State the result before your first edit — "starting from
abc1234, which is currentorigin/main". One line, and it makes a whole class of failure visible immediately instead of at merge time.This matters most in a resumed session. Continuing yesterday's chat reuses yesterday's container: the clone is as old as the session, and the conversation still contains work you believe is unlanded but which was merged hours ago. You then commit on top of a base that no longer exists and re-apply changes already on the live branch. That happened here on 2026-08-21 — a branch whose merge base was 17 commits behind produced a pull request that conflicted by re-adding an FAQ entry already merged.
git statuslooked perfectly healthy throughout, because it was reading a stale cache.If you are stale, rebase onto the live branch or start a fresh branch from it. Do not build on the old base and leave the conflict for a human.
- Never work directly on
main. Create or switch to a branch first, e.g.git checkout -b <descriptive-name>(this repo's own current branch,feat/block-system, is an example of the naming style — short, hyphenated, prefixed by kind of change). - Commit your change with a message describing why, not just what changed. Being asked to make a change is authorization to commit it — a commit on a branch is not the live site, and nothing is published by it existing. Do not stop and ask permission to commit work you were just asked to do.
- Deliver it by whatever channel this platform actually has (see below), then let CI run and let a human merge. This is the review step that makes "an agent may edit this site" safe to say at all. Never merge your own pull request.
Delivery: name your channel before you run anything
Getting the branch up and opening the pull request are two separate steps, and the route for each differs by platform. Work out which route you have before typing a command, and say which one you used.
Getting the branch up:
git push, where the shell has a workingorigin.- The platform's own git integration, where the shell has no
origin. Codex cloud containers have none by design — the task's diff is what gets delivered, not a pushed branch.
Opening the pull request:
- The platform's own Create PR control, wherever one exists — this
outranks the shell. v0, Claude Code cloud, and Codex all show one.
Where there is a control, use it and do not reach for
ghat all. - A GitHub MCP tool, if one is connected to the session.
gh pr create, only once you have confirmed thatghexists and is authenticated here.- Ask the operator, and tell them the branch name and what is on it.
Looking before you run costs one turn. On 2026-08-26 an agent on v0 pushed
its branch successfully, then ran gh pr create, and reported that it
"couldn't create the PR because GitHub CLI authentication isn't configured
in this environment" — while v0's own Create PR button sat in the
toolbar directly above that message. The branch was already on the remote.
Nothing was broken except the choice of route.
Two failures look alarming and are not:
- No
ghbinary, or aghthat is not authenticated. Several platforms ship none, and some ship one with no credentials. Neither is a permissions problem and neither blocks delivery — use the platform's own control. fatal: 'origin' does not appear to be a git repository. Codex cloud containers have no git remote at all, by design: the task's diff is what gets delivered, through the platform, not through a push. Seeing this does not mean the repository connection is broken, and it is not worth retrying — use the platform's own control.
A 403 on push is different from both: that one is a credentials problem,
and it means the session has read access only. Say so plainly rather than
retrying.
Pausing before the pull request
Where you control when the PR opens, pause first: say the change is committed, say what is in it, and ask. A PR is outward-facing — it creates a review artifact, notifies people, and starts CI.
Where the platform's own instructions tell you to create the PR immediately, follow the platform. Its system and developer instructions outrank this file, and there is no safety cost to losing the pause: the PR is not the gate. Nothing reaches the live branch without a human merging it, and on a protected branch GitHub itself refuses anything that skips that path.
Writing the pull request body
This section is about gh in a shell — route 3 above. If you are opening
the pull request through a platform control or an MCP tool, type the body
into that and skip to the trailers section: there is no shell in the path,
so no escaping rule to get wrong.
Never pass a multi-line body as a --body "…" argument. Write it to a
file and use --body-file:
cat > /tmp/pr-body.md <<'EOF'
## The change
What changed, and why.
EOF
gh pr create --title "…" --body-file /tmp/pr-body.mdThis is a mechanical rule, not advice about being careful, because the
failure it prevents is invisible until after the fact. A shell does not
expand \n inside double quotes — it passes a backslash and the letter n.
GitHub stores them, Markdown has no meaning for them, and the entire
description renders as one run-on line with the escapes showing. It happened
here on 2026-08-20 (AGENTS.md §6), and the broken command sat visible in an
approval prompt without anyone spotting it, because nothing about it looks
wrong unless you know the quoting rule.
--body-file has no shell escaping at all, so the defect cannot occur. If
your platform has a PR tool or UI control instead of a shell, use that and
this does not apply.
CI enforces it: the pr-hygiene workflow fails a pull request whose body
carries literal \n escapes, and re-runs when the body is edited, so fixing
it turns the check green without a new commit.
Two things the check cannot judge, which are yours:
- The body must describe the change that was requested. Not the setup you did along the way, not a side effect you swept up. An agent once titled a pull request after a generated file the dev server had rewritten, never mentioning the change the client asked for. Every automated check passed.
- Say what you actually verified. "Ran the checks" when you ran three of eight is worse than saying nothing.
Commit trailers
Land agent-made commits with these two trailers, and no others:
Requested-by: client
Agent: Claude CodeEach trailer goes on its own line, and the same shell rule that mangles a
pull request body mangles a commit message: -m "Requested-by: client\nAgent:
v0" puts a literal backslash and n between them, git reads one trailer whose
value happens to contain two odd characters, and Agent: stops existing. That
shipped on PR #47 on 2026-08-27. Use a second -m, a heredoc, or --file. CI
fails it now (pr-hygiene), but the fix afterwards is an amend and a
force-push, so it is much cheaper to get right the first time.
Requested-by: is whoever asked for the change — client when a client
asked through an agent, or a name when you know it. Agent: is the platform
you are running on: Claude Code, Codex, v0. Both are
plain git trailers, so git log --grep='^Requested-by: client' answers
"what did the client change this month" and git log --grep='^Agent: Codex'
answers "what came through Codex" — which is the provenance a developer
actually wants when a surprising line turns up in a content file.
Do not add vendor attribution trailers. Several platforms append
Co-Authored-By: <model name> and a session URL by default. Strip them.
They credit the model vendor rather than recording who wanted the change,
they put a permanent AI-authorship marker in the history of what may be a
public client repo, and the session link is useless to anyone but the
account that created it.
Get this right at commit time. A trailer is part of the commit message,
so correcting it means git commit --amend and a force-push — a bigger
operation than getting it right once, and one that not every path can carry.
A hosted platform's shell frequently has no git credentials at all, so an
amend typed into a terminal never leaves the container: on 2026-08-21 an
agent read the failing check, diagnosed it correctly, amended the commit, and
could not deliver the fix, and the pull request had to be closed and the work
redone. The platform's own integration may well be able to rewrite the
branch even where its shell cannot — v0 does — so treat a failed force-push
as a fact about the path you took, not about the platform.
So: check the message before you commit. If your platform adds a trailer automatically, remove it in the same step rather than planning to fix it afterwards. And if you find yourself unable to force-push a correction from the shell, do not retry it there — try the platform's own delivery path, and if that is not available say so plainly, quote the corrected message, and ask the operator to push it.
Platform caveat — verify the push actually landed
On some hosted agent platforms the shell has no git credentials configured at
all, and the platform's own git panel (not the shell) is the only channel
that actually talks to the remote. In that situation, git status, git log,
or a cached origin/main can all look completely healthy locally — they're
reading a local cache — while being hours stale, because the shell was never
able to fetch or push in the first place. An agent that assumes shell git
works will commit locally, report success, and silently lose the work: it
never left the sandbox. Before calling a change "shipped," confirm it through
a channel that actually reflects the remote — the platform's own PR/branch
UI, or gh pr view/git ls-remote succeeding — not just a clean local
git status.
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
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.

