How do I install the Debug Pipeline skill?

Run npx skillmds@latest add luishiluy/debug-pipeline in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Debug Pipeline safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Debug Pipeline?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Debug Pipeline free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Debug Pipeline?

LuisHiluy (@luishiluy) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Debug Pipeline by luishiluy — Agent Skill

Name: Debug Pipeline
Author: LuisHiluy

Debug Pipeline

Structured diagnostic runbook for broken AI media pipelines. Walks through symptom → root cause → fix for generator auth failures, stale worker locks, review-app crashes, MCP auth errors, rate limits, and corrupted state files. Use whenever generation jobs fail, workers stop picking up tasks, generated output looks wrong, review tools break, MCP servers error, or any multi-component failure happens in an AI media pipeline. Trigger on "debug the pipeline", "generation is broken", "worker not running", "review app down", "why is this failing", "what's wrong with the pipeline", or anytime the user reports a symptom without yet knowing the root cause.

LuisHiluy 0d4e3ad 4 files · 7.1 KB Updated Sep 17, 2026

File contents

Debug Pipeline — AI Media Runbook

Structured diagnostic for when the generation pipeline breaks.

Quick Diagnostic

Run the full check first:

bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" all

Or target a specific component:

bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" generator
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" worker
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" review-app
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" mcp

Customize the script for your pipeline's components.

Diagnostic Flow

Symptom reported
  ↓
Run check-pipeline.sh all → identify which component is failing
  ↓
Look up symptom in reference/symptom-map.md → follow specific steps
  ↓
Output structured finding:
  - Component: [generator | worker | review-app | mcp | database]
  - Symptom: [what was observed]
  - Root cause: [what the check found]
  - Fix: [specific command or action]
  - Verified: [did the fix work — re-run check-pipeline.sh]

Common Fixes (80% of issues)

Symptom	Fix
Generation stuck	Re-auth the generator
Worker not running	Remove stale lock: `rm runs/worker.lock`, restart
Review app down	Restart servers from launch config
Wrong character	Check prompt uses descriptors not names, add reference images
API rate limit	Back off, reduce parallel batch size

Detailed Symptom Map

For full symptom → diagnostic → fix chains, see reference/symptom-map.md. Extend this file as you discover new failure modes.

Gotchas

Web-auth tokens expire. If anything generation-related fails, check auth first.
Worker lock files persist if the worker crashes. Always check if the PID is actually alive before assuming the worker is running.
Port proxies — if your backend is on port X and your proxy is on port Y, check both. A silent failure on X looks like a failure on Y.
Review data files are often the source of truth for metadata. If they get corrupted, restore from git.

---name: debug-pipelinedescription: Structured diagnostic runbook for broken AI media pipelines. Walks through symptom → root cause → fix for generator auth failures, stale worker locks, review-app crashes, MCP auth errors, rate limits, and corrupted state files. Use whenever generation jobs fail, workers stop picking up tasks, generated output looks wrong, review tools break, MCP servers error, or any multi-component failure happens in an AI media pipeline. Trigger on "debug the pipeline", "generation is broken", "worker not running", "review app down", "why is this failing", "what's wrong with the pipeline", or anytime the user reports a symptom without yet knowing the root cause.---# Debug Pipeline — AI Media RunbookStructured diagnostic for when the generation pipeline breaks.## Quick DiagnosticRun the full check first:```bashbash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" all```Or target a specific component:```bashbash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" generatorbash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" workerbash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" review-appbash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" mcp```Customize the script for your pipeline's components.## Diagnostic Flow```Symptom reported ↓Run check-pipeline.sh all → identify which component is failing ↓Look up symptom in reference/symptom-map.md → follow specific steps ↓Output structured finding: - Component: [generator | worker | review-app | mcp | database] - Symptom: [what was observed] - Root cause: [what the check found] - Fix: [specific command or action] - Verified: [did the fix work — re-run check-pipeline.sh]```## Common Fixes (80% of issues)| Symptom | Fix ||---|---|| Generation stuck | Re-auth the generator || Worker not running | Remove stale lock: `rm runs/worker.lock`, restart || Review app down | Restart servers from launch config || Wrong character | Check prompt uses descriptors not names, add reference images || API rate limit | Back off, reduce parallel batch size |## Detailed Symptom MapFor full symptom → diagnostic → fix chains, see [reference/symptom-map.md](reference/symptom-map.md). Extend this file as you discover new failure modes.## Gotchas- Web-auth tokens expire. If anything generation-related fails, check auth first.- Worker lock files persist if the worker crashes. Always check if the PID is actually alive before assuming the worker is running.- Port proxies — if your backend is on port X and your proxy is on port Y, check both. A silent failure on X looks like a failure on Y.- Review data files are often the source of truth for metadata. If they get corrupted, restore from git.

Frequently asked questions