How to use the Overleaf Sync agent skill (overleaf-sync)

What the overleaf-sync skill makes the agent do

The skill connects a local paper directory with an Overleaf project. Collaborators keep editing in the Overleaf web UI, while ARIS workflows such as /paper-claim-audit, /citation-audit and /auto-paper-improvement-loop run on your local copy. Changes move in both directions through a separate clone called paper-overleaf/.

On a pull, the agent fetches remote edits, shows what changed, and decides per change whether to bring it in. On a push, it copies your local edits into the Overleaf clone, shows the changes, and commits and pushes only after you confirm.

• pull: fetch and review collaborator edits before merging them into paper/
• push: copy local edits into paper-overleaf/, show git diff --stat, then commit and push after confirmation
• status: report whether Overleaf is ahead, local is ahead, both differ, or everything is clean

Check the requirements before you install

The skill needs several things to be in place. Confirm each one before you start, because the setup step depends on them.

• Git
• An Overleaf Premium account with Git bridge access (the skill relies on the Premium Git bridge)
• Your Overleaf project ID or URL
• A credential store: macOS Keychain, Windows Credential Manager, or the Linux cache credential helper
• The ARIS repository tools tools/overleaf_setup.sh and tools/overleaf_audit.sh
• A bash shell

Install the skill by unzipping it or uploading it

Download the ZIP for overleaf-sync from this page. The package contains one file, SKILL.md. You can install it in one of two ways.

For Claude Code, unzip it into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Run the one-time setup in your own terminal

Setup is the only step that involves your Overleaf token, and you run it yourself, not through the agent. The setup script refuses to run unless it is attached to a terminal, reads the token from a hidden prompt, strips the token from the remote URL after cloning, and stores it in your OS keychain.

The script also installs a pre-commit hook in paper-overleaf/.git/hooks/ that refuses to commit any content matching the token pattern olp_ followed by 20 or more letters or digits. When setup finishes, tell the agent 'setup done' and it will verify the clone without touching the token.

• The agent verifies the remote URL has no token, the credential helper is set, git fetch works without prompting, the pre-commit hook exists, and overleaf_audit.sh reports clean
• If paper-overleaf/ is empty because the Overleaf project is new, the agent then copies your local paper/ into it during push

Pull collaborator edits without blind merging

Before each editing session, ask the agent to pull. It runs a fast-forward-only pull and lists the changed files and diffs in sec/*.tex. The skill tells the agent not to merge blindly, because collaborator edits often include half-finished sentences, typos, commented-out blocks, number changes and citation key changes.

The agent classifies each hunk. Clean editorial fixes sync directly. Number or claim changes sync and then trigger /paper-claim-audit. New citations trigger /citation-audit. Half-sentences and obvious typos are flagged for you rather than synced. New sections or restructures wait for your approval.

• Clean editorial improvement: sync, no audit needed
• Numerical or claim change: sync, then re-run /paper-claim-audit
• New \cite{...}: sync, then re-run /citation-audit
• Half-sentence or obvious typo: flag to you, do not auto-sync
• New section or restructure: stop and ask first

Push local edits with a confirmation gate

After ARIS has edited paper/, ask the agent to push. It pulls first to surface remote drift, mirrors paper/ into paper-overleaf/ while excluding build artifacts such as .aux, .log and .synctex.gz files, and shows git status and git diff --stat. It does not run git push until you confirm, unless you said auto: true at the start.

Commit messages name the ARIS skill that made the change, so collaborators can see where an edit came from. Examples from the skill include 'paper-write: regenerated sec/3.assurance after audit cascade refactor' and 'citation-audit: fix 14 metadata entries'.

• Pull happens first on every push
• Build artifacts are excluded from the mirror
• Nothing is pushed until you confirm

Safety notes: scripts, network and the token

The skill runs shell scripts and makes network calls to Overleaf, so read it before you install it. Its allowed tools include Bash, and the source states that the agent never sees your authentication token. Keep it that way: do not paste the token into chat, and do not write it into env vars or files.

If a pull diverges from your local history, the skill does not auto-resolve. It tells the agent to stop and show you the differing commits. It also forbids git reset --hard and git push --force in conflict handling.

• Token is stored in the OS keychain, not in chat history or .git/config
• Divergence between remote and local stops the workflow for your decision
• The skill is MIT licensed