turbo-doctor
Diagnose and fix broken Goldsky Turbo pipelines interactively. Triggers on: pipeline in error state, stuck starting, connection refused, not getting data, duplicate rows, missing fields, slow backfill, or any named pipeline misbehaving. Runs logs/status commands, identifies root cause, and offers fixes. For CLI syntax or error pattern lookup without an active problem, use /turbo-operations instead.
- Installs
- 3.8K
- Last 24h
- +235
- Trending rank
- #1156
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/goldsky-io/goldsky-agent --skill turbo-doctor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads turbo-doctor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Pipeline Doctor
Boundaries
- Diagnose and fix EXISTING pipeline problems interactively.
- Do not build new pipelines — that belongs to
/turbo-builder. - Do not serve as a command reference. If the user only needs CLI syntax or error pattern lookup, use the
/turbo-operationsskill instead.
Systematically identify and resolve pipeline issues by following a structured diagnostic workflow.
Mode Detection
Before running any commands, check if you have the Bash tool available:
- If Bash is available (CLI mode): Execute commands directly and parse output.
- If Bash is NOT available (reference mode): Output commands for the user to run. Ask them to paste the output back so you can analyze it and provide recommendations.
Diagnostic Workflow
Follow these steps in order. Do not skip steps — each builds on the previous one.
Step 1: Verify Authentication
Run goldsky project list 2>&1 to check login status.
- If logged in: Note the current project and continue.
- If not logged in: Tell the user they need to authenticate. Use the
/auth-setupskill for guidance. Do not proceed until auth is confirmed.
Step 2: Identify the Pipeline
Run goldsky turbo list to show all pipelines.
Ask the user which pipeline they want to diagnose. If they already named one, confirm it exists in the list.
Note the pipeline's current status (running, paused, error, completed, starting).
Step 3: Analyze Pipeline Status
Based on the status:
- running — Pipeline is active. Check if the issue is data quality, latency, or unexpected behavior. Proceed to Step 4.
- error — Pipeline has failed. This is the most common case. Proceed to Step 4 for log analysis.
- paused — Pipeline was manually paused. Ask if they want to resume it.
- starting — Pipeline is initializing. Ask how long it's been starting. If >10 minutes, check logs.
- completed — Job-mode pipeline finished. Ask what the expected vs actual behavior was.
Step 4: Examine Logs
Run goldsky turbo logs <pipeline-name> --tail 100 2>&1 to get recent logs.
Analyze the output for known error patterns. Reference the error patterns in the /turbo-operations skill, including:
- Connection errors — sink unreachable, auth failed, timeout
- Schema errors — column mismatch, type mismatch, missing columns
- Resource errors — OOM, disk full, rate limiting
- Data errors — deserialization failures, invalid block ranges
- Configuration errors — invalid YAML, unknown dataset, bad transform
Step 5: Check Secrets (if applicable)
If logs show connection or authentication errors:
Run goldsky secret list to verify all required secrets exist.
Cross-reference with the pipeline YAML if available. Use the /secrets skill for guidance on creating or updating secrets.
Step 6: Provide Diagnosis
Present your findings in this format:
## Diagnosis
**Pipeline:** [name]
**Status:** [status]
**Issue:** [one-line summary]
**Root cause:**
[Detailed explanation of what's wrong]
**Evidence:**
- [Log line or observation 1]
- [Log line or observation 2]
**Recommended fix:**
1. [Step 1]
2. [Step 2]
**Prevention:**
[How to avoid this in the future]
Step 7: Offer to Fix
If the fix involves CLI commands (restart, update secrets, redeploy), offer to execute them. Always confirm with the user before making changes.
Common fixes:
- Restart:
goldsky turbo restart <name>(or--clear-statefor a fresh start) - Update secret: Use
goldsky secret update <name> --value "$(cat /secure/path/secret.json)"to rotate the existing secret in place; see Rotating Credentials for the JSON format and credential handling. Do not delete and recreate an in-use secret. Unlikecreate,updatedoes not prompt for a value. Never echo credentials back into the conversation. - Redeploy:
goldsky turbo delete <name>thengoldsky turbo apply <file.yaml> - Resume:
goldsky turbo resume <name>(for paused pipelines)
Important Rules
- Never guess at the problem. Always check logs and status first.
- If you're unsure, say so and suggest what additional information would help.
- For job-mode pipelines: remember they cannot be paused, resumed, or restarted — only deleted and redeployed.
- Always ask before running destructive commands (delete, restart --clear-state).
- If the issue is beyond what the CLI can diagnose, suggest contacting Goldsky support with the specific error messages.
Related
/turbo-operations— CLI commands, lifecycle operations, and error pattern reference/turbo-builder— Build and deploy new pipelines/turbo-pipelines— YAML configuration and architecture reference/secrets— Manage sink credentials
FAQ
What does the turbo-doctor skill do?
Diagnose and fix broken Goldsky Turbo pipelines interactively. Triggers on: pipeline in error state, stuck starting, connection refused, not getting data, duplicate rows, missing fields, slow backfill, or any named pipeline misbehaving. Runs logs/status commands, identifies root cause, and offers fixes. For CLI syntax or error pattern lookup without an active problem, use /turbo-operations instead.
How do I install turbo-doctor?
Run npx skills add https://github.com/goldsky-io/goldsky-agent --skill turbo-doctor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/turbo-doctor/ (personal) or .claude/skills/turbo-doctor/ (project).
Which AI agents can use turbo-doctor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is turbo-doctor safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains turbo-doctor?
It is published by goldsky-io in goldsky-io/goldsky-agent. It has 3,792 recorded installs.
More from goldsky-io/goldsky-agent
turbo-pipelines
goldsky-io/goldsky-agent
Turbo pipeline YAML reference and architecture guide. Covers: YAML field syntax (startat, from, version, primarykey), source/transform/sink configuration, validation errors, resource sizing (xs–xxl), architecture decisions (dataset vs kafka, streaming vs job, fan-out vs fan-in, sink selection, pipeline splitting). Triggers on: 'what does field X do', 'what fields does a postgres sink need', 'what resource size', 'should I use kafka or dataset', 'how to structure my pipeline'. For writing transforms, use /turbo-transforms. For end-to-end building, use /turbo-builder.
turbo-transforms
goldsky-io/goldsky-agent
Write SQL, TypeScript, and dynamic table transforms for Turbo pipelines. Covers: decoding EVM logs with gslogdecode, filtering/casting blockchain data, UNION ALL for combining events, TypeScript/WASM transforms (invoke function), dynamic lookup tables (dynamictablecheck), transform chaining, and Solana decoding. Triggers on: 'decode Transfer events', 'write a SQL transform', 'filter by contract', 'TypeScript transform', 'dynamic table', 'UNION ALL'. For pipeline YAML structure, use /turbo-pipelines. For end-to-end building, use /turbo-builder.
turbo-builder
goldsky-io/goldsky-agent
Build and deploy new Goldsky Turbo pipelines: requirements, dataset selection, YAML, validation, and deployment. Use for 'build a pipeline', 'index X on Y chain', or moving chain/contract data into Postgres, MySQL, ClickHouse, Kafka, Pub/Sub, S3, SQS, or webhooks. Also use for data goals such as Polymarket fills/positions/PnL, prediction markets, stablecoin or circulating supply, proof of reserves, sanctions/AML transfer monitoring, deposit detection, CCTP burns/mints, cross-chain settlement, payment reconciliation, wallet history streamed into the user's own database, token holder registries, tokenized equities/RWA, and wash-trading detection. A REST lookup of one wallet's balances or transfers is /feeds, not a pipeline, and so is a read of Polymarket activity, positions or balances. Debug existing pipelines with /turbo-doctor; look up syntax with /turbo-pipelines.
datasets
goldsky-io/goldsky-agent
Use this skill when the user needs to look up or verify Goldsky blockchain dataset names, chain prefixes, dataset types, or versions. Triggers on questions like 'what\'s the dataset name for X?', 'what prefix does Goldsky use for chain Y?', 'what version should I use for Z?', or 'what datasets are available for Solana/Stellar/Arbitrum/etc?'. Also use for chain-specific dataset questions (e.g., polygon vs matic prefix, stellarnet balance datasets, solana token transfer dataset names), and to answer 'is there a dataset for X?' where X is a domain rather than a chain — decoded logs, token transfers and balances, mint/burn events for circulating supply, DEX or prediction-market activity (Polymarket), or the raw blocks, transactions and traces behind wallet history and reconciliation. Do NOT trigger for questions about CLI commands, pipeline setup, or general Goldsky architecture unless the core question is about finding the right dataset name or chain prefix. Wallet Feeds API queries are /
auth-setup
goldsky-io/goldsky-agent
Set up Goldsky CLI authentication and project configuration. Use this skill when the user needs to: install the goldsky CLI (what's the official install command?), run goldsky login (including when the browser opens but 'authentication failed'), run goldsky project list and see 'not logged in' or 'unauthorized', switch between Goldsky projects, check which project they're currently authenticated to, or fix 'unauthorized' errors when running goldsky turbo commands. Also use for 'walk me through setting up goldsky CLI from scratch for the first time', and when they just installed Goldsky and say 'Set it up and help me get started'. If any other Goldsky skill hits an auth error, redirect here first.
turbo-operations
goldsky-io/goldsky-agent
Turbo pipeline operations reference — lifecycle commands (pause, resume, restart, delete), pipeline states, checkpoint behavior, streaming vs job-mode differences, CLI syntax for inspect/logs, TUI shortcuts, and error pattern lookup. Triggers on: 'how do I pause/restart/delete', 'will deleting lose my data', 'what does this error mean', 'inspect TUI shortcuts'. For interactive diagnosis of a broken pipeline, use /turbo-doctor.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.