New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Workers Sync Debugger

by makenotion in makenotion/workers-template

Works out why a Workers sync is failing or returning wrong data by reading run logs through the ntn CLI, matching errors to the sync code and proposing fixes.

OfficialMITAuto-check: notesBackend & APIs

Install Workers Sync Debugger

skills CLI
$ npx skills add makenotion/workers-template --skill sync-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install makenotion/workers-template sync-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/makenotion/workers-template.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/sync-debug .claude/skills/sync-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
sync-debug
GitHub stars
441
Used in
1 other repo
Token cost
~957 tokens
SKILL.md length
493 words
Files
1
Skills in repo
5
Repo updated
First seen
Licence
MIT

At a glance

Works out why a Workers sync is failing or returning wrong data by reading run logs through the ntn CLI, matching errors to the sync code and proposing fixes.

  • Works in 6 steps: Get Current State → Fetch Recent Runs → Get Logs → …
  • A scheduled sync has stopped producing data or keeps failing
  • Calls npm
  • Run logs show 401, 403 or 429 errors from an upstream API

What it does

The agent follows a fixed sequence. It checks sync status with ntn workers sync status, lists recent runs to spot non-zero exit codes, then fetches logs for the latest run or for a named sync. It reads src/index.ts and any imported modules, and matches each error from the logs against the code before naming a cause.

The diagnosis section lists common patterns and the fix for each. Authentication errors with 401 or 403 point to OAuth tokens and missing environment variables, which can be pushed with ntn workers env push. Rate limits at 429 and timeouts call for smaller batches. State errors after a code change are cleared by resetting the sync state, and schema mismatches mean change properties disagree with the declared schema. The excerpt is cut off, so further patterns may exist.

When your agent uses it

  • A scheduled sync has stopped producing data or keeps failing
  • Run logs show 401, 403 or 429 errors from an upstream API
  • A sync reports state or schema errors after a code change

Example prompts

  • “My product sync failed overnight; find out why and suggest a fix.”
  • “Read the latest run logs for the orders sync and compare them with src/index.ts.”
  • “The sync now throws a TypeError on state after my last edit. Diagnose it.”

Requirements

  • The `ntn` CLI with access to the deployed Workers
  • A Workers project whose sync code lives in `src/index.ts`
  • Pre-approved tools (allowed-tools): Read, Bash, Glob, Grep, Edit, Write

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Get Current State
  2. Fetch Recent Runs
  3. Get Logs
  4. Read the Sync Code
  5. Diagnose
  6. Fix and Verify

What it can do on your machine

Read from SKILL.md and the folder at commit 681d89d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Bash
    • Glob
    • Grep
    • Edit
    • Write

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Workers Sync Debugger loads about 957 tokens when it runs. Until then it costs about 32 tokens; SKILL.md has 493 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~32
When it runs · the whole SKILL.md, loaded when a task matches
~957

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Bash, Glob, Grep, Edit, Write

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from makenotion/workers-template at commit 681d89d, republished under its MIT licence (© makenotion). 493 words, ~957 tokens.

Download SKILL.mdSave it as .claude/skills/sync-debug/SKILL.md (or your agent's skills folder).
name
sync-debug
description
Diagnose a failing or misbehaving sync — fetch run logs, identify errors, cross-reference with code, and suggest fixes
allowed-tools
Read, Bash, Glob, Grep, Edit, Write
user-invocable
true
disable-model-invocation
true

Instructions

Help the user figure out why their sync is failing or producing wrong results. Work through the steps below systematically.

Step 1: Get Current State

Run these commands to understand the situation:

shell
ntn workers sync status

Note which syncs are listed, their status, last run time, and next scheduled run. Look for syncs that are stuck, failing, or haven't run recently.

Step 2: Fetch Recent Runs
shell
ntn workers runs list

Look for runs with non-zero exit codes (shown in red in table output). Note the run IDs for failed runs.

Step 3: Get Logs

For the most recent run (any capability):

shell
ntn workers runs list --plain | head -n1 | cut -f1 | xargs -I{} ntn workers runs logs {}

For the most recent run of a specific sync:

shell
ntn workers runs list --plain | grep <syncKey> | head -n1 | cut -f1 | xargs -I{} ntn workers runs logs {}

Read the full log output. Look for error messages, stack traces, and any console.log output from the sync code.

Step 4: Read the Sync Code

Read src/index.ts (and any imported modules) to understand the sync's logic. Cross-reference the error from the logs with the code.

Step 5: Diagnose

Common failure patterns and their fixes:

API Authentication Errors (401/403)

  • Check if OAuth is configured: ntn workers oauth token <oauthKey>
  • Check environment variables: ntn workers env list
  • If env vars are missing remotely: ntn workers env push
  • If OAuth token expired: ntn workers oauth start <key> to re-authenticate

Rate Limiting (429)

  • Reduce batch size in the sync code
  • Add delays between API calls if needed
  • Check if the API has documented rate limits

Timeout / Long Execution

  • The execute function is taking too long per call
  • Reduce batch size (fewer records per page)
  • Simplify per-record processing (defer heavy transforms)

Cursor / State Errors

  • TypeError on state access: probably a first-run issue (state is undefined)
  • State shape changed after a code update: the persisted state from the previous run has the old shape
  • Fix: ntn workers sync state reset <key> to clear state and re-backfill from scratch

Schema Mismatch

Show full SKILL.md (196 more words)Show less
  • Properties in changes don't match the schema.properties definition
  • Check that every key in the properties object of each change matches a key in the schema
  • Check that Builder.title() is used for Schema.title() properties, Builder.richText() for Schema.richText(), etc.

Infinite Loop (sync never completes)

  • hasMore is always true — the cursor isn't advancing
  • Check that nextState changes between iterations
  • Check the termination condition: is it reachable?

Empty Results

  • API returning no data: test the API call directly (curl or local exec)
  • Wrong endpoint or query parameters
  • Auth working but insufficient permissions/scopes

Network / Transient Errors

  • Single occurrence: may be transient — check if subsequent runs succeeded
  • Repeated: check the API endpoint URL, DNS, connectivity
  • Force a retry: ntn workers sync trigger <key>
Step 6: Fix and Verify

After identifying the issue:

  1. Apply the fix to the code
  2. Run npm run check to verify types
  3. If the state shape changed, warn the user they may need ntn workers sync state reset <key> (this triggers a full re-backfill)
  4. Deploy and preview to verify: suggest /sync-preview or run ntn workers deploy && ntn workers sync trigger <key> --preview
  5. When the fix is verified, ntn workers sync trigger <key> to resume

© makenotion, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/sync-debug of makenotion/workers-template.

Open the folder on GitHubat commit 681d89d

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in makenotion/workers-template, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Workers Sync Debugger next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Workers Sync Debugger compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Workers Sync Debugger this skillmakenotion/workers-template4411 repos~957Automated safety check: NotesMIT
QA Find Bugs MCPbex-co/beancount-io294—~3kAutomated safety check: PassMIT
Debugging Mwaa Workflowaws/agent-toolkit-for-aws2.8k—~2.3kAutomated safety check: PassApache-2.0
Flowfile Debugging PlaybookEdwardvaneechoud/Flowfile370—~6.3kAutomated safety check: PassMIT
Debugging Lambda Timeoutsaws/agent-toolkit-for-aws2.8k—~502Automated safety check: PassApache-2.0
Pester Failure AnalysisPowerShell/PowerShell56k—~5.1kAutomated safety check: PassMIT

Similar skills

  • QA Find Bugs MCP

    bex-co/beancount-io

    Hunt bugs in the Beancount.io remote MCP server by driving the real POST /api-gateway/mcp endpoint with JSON-RPC and real MCP clients, checking transport, discovery, credential boundaries, tool and…

    294 GitHub stars~3k tokensUpdated today
    Backend & APIsAuto-check passed

  • Debugging Mwaa Workflow

    aws/agent-toolkit-for-aws

    Official

    Diagnoses and root-causes Amazon MWAA workflow failures across Provisioned (Python DAG) and Serverless (YAML workflow) environments.

    2.8k GitHub stars~2.3k tokensUpdated today
    Backend & APIsAuto-check passed

  • Flowfile Debugging Playbook

    Edwardvaneechoud/Flowfile

    Symptom-to-cause triage playbook for Flowfile (core/worker/kernel/frontend/AI) — covers "no such table" DB cascades (two distinct causes), import-time Alembic migration corruption, silent…

    370 GitHub stars~6.3k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Debugging Lambda Timeouts

    aws/agent-toolkit-for-aws

    Official

    Debugs AWS Lambda function timeout failures by systematically analyzing function configuration, CloudWatch logs and metrics, VPC/networking, cold starts, memory constraints, and downstream…

    2.8k GitHub stars~502 tokensUpdated today
    DevelopmentAuto-check passed

  • Pester Failure Analysis

    PowerShell/PowerShell

    Investigates failing Pester tests in PowerShell CI jobs by following a six-step workflow from pull request status to documented fix recommendations.

    56k GitHub stars~5.1k tokensUpdated today
    Testing & QAAuto-check passed

  • OpenLogi macOS Permissions Triage

    AprilNEA/OpenLogi

    Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated 4 days ago
    DevelopmentAuto-check: notes

More from makenotion/workers-template

  • Notion Worker Third-Party Auth Guide

    makenotion/workers-template

    Official

    Decides whether a Notion Worker should use a brokered credential, a plaintext environment secret, or OAuth to authenticate against a non-Notion service.

    441 GitHub starsUsed in 1 repo~3.5k tokens
    Auto-check: notes

  • Notion Worker Sync Scaffold

    makenotion/workers-template

    Official

    Walks you through designing a new sync for a Notion Worker, covering data source, mode, pagination and cursors, and then generates working code.

    441 GitHub starsUsed in 1 repo~4.6k tokens
    Auto-check: notes

  • Notion Workers Sync Guide

    makenotion/workers-template

    Official

    Guides the design of Notion Workers syncs, from choosing a simple replace sync or a backfill plus delta pair to pagination, consistency buffers, pacing and deletion handling.

    441 GitHub starsUsed in 1 repo~3k tokens
    Auto-check passed

  • Sync Capability Validator

    makenotion/workers-template

    Official

    Checks a Workers sync capability against a list of common bugs, such as stuck cursors, endless pagination and lost deletions, and reports by severity.

    441 GitHub starsUsed in 1 repo~1.2k tokens
    Auto-check: notes

Categories

Questions about Workers Sync Debugger

What does Workers Sync Debugger do?

Works out why a Workers sync is failing or returning wrong data by reading run logs through the ntn CLI, matching errors to the sync code and proposing fixes. The agent follows a fixed sequence. It checks sync status with ntn workers sync status, lists recent runs to spot non-zero exit codes, then fetches logs for the latest run or for a named sync.

When should I use Workers Sync Debugger?

Workers Sync Debugger fits situations like: A scheduled sync has stopped producing data or keeps failing; run logs show 401, 403 or 429 errors from an upstream API; A sync reports state or schema errors after a code change.

How do I install Workers Sync Debugger in Claude Code?

Run `npx skills add makenotion/workers-template --skill sync-debug -a claude-code`. Or copy the skill folder (.agents/skills/sync-debug in makenotion/workers-template) into .claude/skills/sync-debug in your project. Claude Code loads it when a task matches its description.

How do I install Workers Sync Debugger in Codex?

Run `npx skills add makenotion/workers-template --skill sync-debug -a codex`. Or copy the skill folder (.agents/skills/sync-debug in makenotion/workers-template) into .agents/skills/sync-debug in your project. Codex loads it when a task matches its description.

Can I use Workers Sync Debugger in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add makenotion/workers-template --skill sync-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/sync-debug, .gemini/skills/sync-debug, .github/skills/sync-debug and .opencode/skills/sync-debug in your project.

What does Workers Sync Debugger need to run?

Going by SKILL.md and its folder, Workers Sync Debugger needs the command-line tools its instructions call (npm). Our summary lists: The `ntn` CLI with access to the deployed Workers; A Workers project whose sync code lives in `src/index.ts`. Its frontmatter pre-approves these tools: Read, Bash, Glob, Grep, Edit, Write.

Does Workers Sync Debugger access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Workers Sync Debugger safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Workers Sync Debugger use?

Workers Sync Debugger is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Workers Sync Debugger use?

About 957 tokens (SKILL.md is roughly 3.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Workers Sync Debugger?

Skills that share tags, products or a category with Workers Sync Debugger: QA Find Bugs MCP (bex-co/beancount-io, 294 stars), Debugging Mwaa Workflow (aws/agent-toolkit-for-aws, 2.8k stars), Flowfile Debugging Playbook (Edwardvaneechoud/Flowfile, 370 stars) and Debugging Lambda Timeouts (aws/agent-toolkit-for-aws, 2.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Workers Sync Debugger?

makenotion (a GitHub organization, an official publisher) maintains it in makenotion/workers-template, which has 441 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on September 11, 2026.

Source: makenotion/workers-template on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.