AGENTS.md git:20261105.79c6c59A

Immutable. This exact content never changes and is served at /api/v1/blob/4bc92509a74678b2.

# Working on this repo

This repo is the public home of the sync. labs agent skills. It ships to skills.sh (`npx skills add synchronicity-labs/skills`), the Claude Code plugin marketplace (`.claude-plugin/`), Codex (`.codex-plugin/`) and Cursor (`.cursor-plugin/`).

## Layout

- `skills/<name>/SKILL.md` is the skill. `references/` holds detail it loads on demand, `scripts/` holds bundled code, and `agents/openai.yaml` is the Codex display metadata.
- `shared/` holds reference files several skills use. `scripts/sync_shared.py` copies them into each skill's `references/`, because a skill installed on its own must carry everything it links to. Edit the shared file, never a copy.
- `docs/<name>.md` is the human-facing page for each skill: what it does, when to reach for it, what you need, common questions, and how to tell it's working. `docs/overview.md` is the landing page. These files are the source of the Agent Skills section on sync.so/docs: the docs site (synchronicity-labs/sync-fern) downloads this repo when it builds and converts them, so a change merged here goes live without a docs change. Page order comes from `catalog.json`.
- `docs/i18n/<locale>/<page>.md` are the Spanish (`es`), French (`fr`), Brazilian Portuguese (`pt-BR`) and German (`de`) translations, and `meta.json` next to them holds the navigation labels.
- `skills.sh.json` groups the skills on the skills.sh repo page. Put every new skill in one grouping.
- `catalog.json` is generated by `scripts/build_catalog.py` from each skill's frontmatter and `agents/openai.yaml`. Studio and the docs read it from GitHub, so a merged change shows up there without their own release. Regenerate it with every skill change.
- `evals/` is a `claude plugin eval` suite. Cases are generated by `scripts/build_evals.py`.

## Rules

- When you add, rename or change a skill, update its `docs/<name>.md` and that page's translations, its `agents/openai.yaml`, the README table, the skills table in `docs/overview.md` and `CHANGELOG.md` in the same change.
- Skills never hardcode prices, plan limits or model lists. They read them from the tools (`generate_estimate-cost`, `get-account-context`, `models_get`) so they stay correct as the product changes.
- Every paid action is quoted first and waits for approval, unless the user already approved that exact request and cost.
- Every create call carries an idempotency key that is saved before the call and reused on retries.
- No em dashes or en dashes anywhere, in every language. Rewrite the sentence with a comma, colon, period or "to" for ranges.

## Docs pages

Write the pages in plain Markdown that reads well on GitHub. The docs site converts a few patterns:

- Front matter: `title`, `subtitle`, `description` and `og:description` (plus an optional shorter `og:subtitle` for the social image). Quote every value. The docs site adds the date, social image and `og:title`.
- The first `# ` heading is dropped (the title shows instead). `> [!TIP]`, `> [!NOTE]` and `> [!WARNING]` become callouts.
- A line that is entirely `**bold**` followed directly by its answer becomes a collapsible question. Keep each answer to one paragraph.
- `1. **Step title**` items with their content indented three spaces become steps.
- `<!-- card icon="..." -->` before a `**[title](url)**` line and its description makes a card. `<!-- llms-ignore -->` and `<!-- /llms-ignore -->` hide a block from the AI index.
- Link other pages as `name.md` and other docs pages as `https://sync.so/docs/...`; both become site links. No other relative links, and no `<`, `{` or `}` outside code.

Any change to an English page updates all four translations in the same change: translate the change, then set the translation's `source-sha256` to the sha256 of the new English file (`shasum -a 256 docs/<page>.md`). The validator fails when a translation is missing, stale or has no English page. Keep each language's voice: Spain Spanish with tú, French with vous, Brazilian Portuguese with você, German with du. Keep skill names, commands, URLs and code in English, and translate example prompts but not the paths or URLs inside them.

## Check a change

```bash
python3 scripts/sync_shared.py      # refresh shared copies
python3 scripts/build_catalog.py    # refresh catalog.json
python3 scripts/validate.py         # frontmatter, links, tool names, manifests, docs pages and translations, dashes
python3 -m unittest discover -s tests
claude plugin validate .
claude plugin eval . --tag <skill> --runs 2 --ablation none --scaffold --trust-plugin --allow-tools Bash Write Edit
```

The SDK sample tests need `SYNC_TEST_PYTHON` (a Python with `syncsdk`) and `SYNC_TEST_NODE_MODULES` (with `@sync.so/sdk`, `typescript` and `@types/node`). Set `SYNC_TEST_REQUIRE_SDKS=1` to fail instead of skipping when they're missing.