From qencode-skills
Use when a Qencode transcoding job or API call has failed and the user wants help understanding why. Triggers — "what does error N mean?", "my job failed", "why is this error happening?", "Qencode returned error 19", "the status shows error_description X", or any time the user pastes a non-zero `error` code or a `failed`/`error` status payload. Maps the error to its likely cause, suggests concrete fixes, and (when relevant) inspects the original query JSON for misconfigurations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qencode-skills:qencode-troubleshootThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You diagnose Qencode failures and recommend fixes. You do **not** re-submit, re-encode, or modify the user's project — diagnosis only. If the user wants to fix and re-run, hand the suggested change to `qencode-build-query` (to regenerate the query) or `qencode-transcode` (to re-submit).
You diagnose Qencode failures and recommend fixes. You do not re-submit, re-encode, or modify the user's project — diagnosis only. If the user wants to fix and re-run, hand the suggested change to qencode-build-query (to regenerate the query) or qencode-transcode (to re-submit).
The user typically gives you one or more of:
error 19, Qencode error 8.error_description string from a failed job's /v1/status response.qencode-job-status first.If they only said "my job failed" without context, ask for at minimum the error code OR the failed task_token. Don't guess from nothing.
Identify the layer. API-level error vs job-level error matters — they're diagnosed differently.
| Signal | Layer |
|---|---|
Synchronous response from POST /v1/... has error: <N> where N ≠ 0 | API-level |
/v1/status response shows status: "error" or "failed" with error_description: "..." | Job-level |
Callback payload with event: "error" and an error_code field | API-level (use the error_code) |
Look up the error. Read ${CLAUDE_PLUGIN_ROOT}/assets/error-codes.md.
error_description to one.Cross-reference with gotchas. Read ${CLAUDE_PLUGIN_ROOT}/assets/gotchas.md. Some errors are non-obvious — for example, error 19 is a query-wrapping issue, and "permission denied" on a Cloudflare R2 destination is the permissions field trap.
Inspect context when the user shared it:
best-practices.md. If the failure is destination-related, check the destination shape against storage.md per-provider compatibility.curl -I <url> to confirm reachability and content-type. If the user can't run shell commands, ask them to.storage.md.qencode-job-status for the full failed status payload (warnings, partial outputs, exact error_description).Recommend a fix. Output format:
Diagnosis
Error:
<code or category>—<short title>Likely cause: <1–2 sentences>Suggested fix
<numbered list of concrete actions — change X to Y, run command Z, etc.>
Verify
<how to confirm the fix worked: a curl command, a test job shape, expected status response, etc.>
Cross-references
assets/error-codes.md§assets/gotchas.md§assets/storage.md(if destination-related)
Lead with the most-likely cause, but list 1–2 alternates if the symptom is ambiguous. Be specific — "set permissions: \"public-read\" only on AWS, omit on Qencode S3" beats "fix the permissions".
Escalate when needed. If the error matches the "Internal server error" codes (1, 7), the user has already exhausted documented fixes, OR the symptom doesn't match anything in error-codes.md:
Next step: This looks like a backend issue rather than a config problem. Collect the full request body (credentials redacted) and the full response, then email
[email protected]or open a ticket at https://portal.qencode.com. Include thetask_tokenif you have one — it lets support trace the job through their logs.
error-codes.md. If the user reports an undocumented code, say so and apply the generic fallback./troubleshoot-job skill that uses infra access.)qencode-build-query + qencode-transcode themselves once they agree.${CLAUDE_PLUGIN_ROOT}/assets/error-codes.md — full error code table${CLAUDE_PLUGIN_ROOT}/assets/gotchas.md — non-obvious quirks behind common errors${CLAUDE_PLUGIN_ROOT}/assets/storage.md — destination-related failures${CLAUDE_PLUGIN_ROOT}/assets/best-practices.md — composition defaults a failing query may have violated${CLAUDE_PLUGIN_ROOT}/skills/qencode-job-status/SKILL.md — fetch the failed status first if only a token was provided${CLAUDE_PLUGIN_ROOT}/skills/qencode-build-query/SKILL.md — regenerate the corrected querynpx claudepluginhub qencode-corp/qencode-skills --plugin qencode-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.