AGENTS.md git:20261105.10a5dc1A

Immutable. This exact content never changes and is served at /api/v1/blob/2ab19e8953c7e836.

# 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. The same pages are published on sync.so/docs.
- `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`, its `agents/openai.yaml`, the README table 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. Rewrite the sentence with a comma, colon, period or "to" for ranges.

## 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, 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.