{"id":"f98158bb-378d-4c71-8b91-d7297bf44ab2","shortId":"ggyhZ8","kind":"skill","title":"withheld-max-output-token-errors","tagline":"Delay surfacing max-output-token failures until the recovery loop completes, then emit sanitized tool_result errors.","description":"# SKILL: Withheld Max Output Token Errors\n**Domain:** tool-orchestration  \n**Trigger:** Use this when a user turn hits the max-output-token limit but the system keeps retrying so the recovery loop should finish before reporting an error.\n**Source Pattern:** Distilled from reviewed tool-loop and result-shaping patterns.\n\n## Core Method\nDetect the API’s `max_output_tokens` error inside the streaming loop, suppress it while recovery continues, and only expose it once all retries settle. During that delay, emit placeholder `tool_result` messages that say each tool is missing so the user sees a focused failure summary instead of a raw API error. This keeps recovery logic intact while still surfacing helpful, per-tool diagnostics after the recovery path finishes.\n\n## Key Rules\n- Guard every assistant message against `apiError === 'max_output_tokens'` and only mark it for reporting once the recovery loop decides no more progress can happen.\n- Track tool_use IDs for the assistant messages that triggered the error and emit sanitized messages with the standard `tool_result` shape so downstream components can handle them like any other tool failure.\n- Log the withheld message only after `isWithheldMaxOutputTokens` returns true; do not surface the API error early or the SDK context may terminate the session.\n- Keep the placeholder text short, include the original error message, and mark `is_error: true` so tooling knows it’s still an error.\n- Preserve the tool ID so any transcripts or sidecars referencing the tool use still match the replayed replacement.\n\n## Example Application\nWhen the per-turn token budget is exceeded while streaming a multi-tool answer, let the recovery loop run; once it fails, emit one user-facing `tool_result` block per tool use with the stored error message instead of leaking the API’s `max_output_tokens` field.\n\n## Anti-Patterns (What NOT to do)\n- Do not throw or propagate the API error immediately; SDK callers might abort and the recovery path would never execute.\n- Do not drop the tool_use IDs when rewriting the error, or transcripts/resumes will lose their references.","tags":["withheld","max","output","token","errors","cskill","agents","ychampion","agent-skills","ai-agents","cli","coding-agents"],"capabilities":["skill","source-ychampion","skill-withheld-max-output-token-errors","topic-agent-skills","topic-ai-agents","topic-cli","topic-coding-agents","topic-context-engineering","topic-developer-tools","topic-mcp","topic-multi-agent","topic-terminal-ui"],"categories":["cskill-agents"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ychampion/cskill-agents/withheld-max-output-token-errors","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ychampion/cskill-agents","source_repo":"https://github.com/ychampion/cskill-agents","install_from":"skills.sh"}},"qualityScore":"0.467","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 34 github stars · SKILL.md body (2,120 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T00:56:58.780Z","embedding":null,"createdAt":"2026-04-18T22:21:40.237Z","updatedAt":"2026-04-22T00:56:58.780Z","lastSeenAt":"2026-04-22T00:56:58.780Z","tsv":"'abort':346 'answer':292 'anti':328 'anti-pattern':327 'api':81,130,223,321,340 'apierror':157 'applic':276 'assist':154,183 'block':308 'budget':283 'caller':344 'complet':18 'compon':201 'context':229 'continu':95 'core':77 'decid':171 'delay':7,106 'detect':79 'diagnost':144 'distil':66 'domain':31 'downstream':200 'drop':356 'earli':225 'emit':20,107,190,301 'error':6,24,30,63,86,131,188,224,242,247,256,315,341,364 'everi':153 'exampl':275 'exceed':285 'execut':353 'expos':98 'face':305 'fail':300 'failur':13,124,209 'field':326 'finish':59,149 'focus':123 'guard':152 'handl':203 'happen':176 'help':140 'hit':42 'id':180,260,360 'immedi':342 'includ':239 'insid':87 'instead':126,317 'intact':136 'iswithheldmaxoutputtoken':216 'keep':52,133,234 'key':150 'know':251 'leak':319 'let':293 'like':205 'limit':48 'log':210 'logic':135 'loop':17,57,71,90,170,296 'lose':368 'mark':163,245 'match':271 'max':3,10,27,45,83,158,323 'max-output-token':9,44 'may':230 'messag':111,155,184,192,213,243,316 'method':78 'might':345 'miss':117 'multi':290 'multi-tool':289 'never':352 'one':302 'orchestr':34 'origin':241 'output':4,11,28,46,84,159,324 'path':148,350 'pattern':65,76,329 'per':142,280,309 'per-tool':141 'per-turn':279 'placehold':108,236 'preserv':257 'progress':174 'propag':338 'raw':129 'recoveri':16,56,94,134,147,169,295,349 'refer':370 'referenc':266 'replac':274 'replay':273 'report':61,166 'result':23,74,110,197,307 'result-shap':73 'retri':53,102 'return':217 'review':68 'rewrit':362 'rule':151 'run':297 'sanit':21,191 'say':113 'sdk':228,343 'see':121 'session':233 'settl':103 'shape':75,198 'short':238 'sidecar':265 'skill':25 'skill-withheld-max-output-token-errors' 'sourc':64 'source-ychampion' 'standard':195 'still':138,254,270 'store':314 'stream':89,287 'summari':125 'suppress':91 'surfac':8,139,221 'system':51 'termin':231 'text':237 'throw':336 'token':5,12,29,47,85,160,282,325 'tool':22,33,70,109,115,143,178,196,208,250,259,268,291,306,310,358 'tool-loop':69 'tool-orchestr':32 'topic-agent-skills' 'topic-ai-agents' 'topic-cli' 'topic-coding-agents' 'topic-context-engineering' 'topic-developer-tools' 'topic-mcp' 'topic-multi-agent' 'topic-terminal-ui' 'track':177 'transcript':263 'transcripts/resumes':366 'trigger':35,186 'true':218,248 'turn':41,281 'use':36,179,269,311,359 'user':40,120,304 'user-fac':303 'withheld':2,26,212 'withheld-max-output-token-error':1 'would':351","prices":[{"id":"e0100c10-491b-4183-8533-c5a02a8c5f56","listingId":"f98158bb-378d-4c71-8b91-d7297bf44ab2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ychampion","category":"cskill-agents","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:40.237Z"}],"sources":[{"listingId":"f98158bb-378d-4c71-8b91-d7297bf44ab2","source":"github","sourceId":"ychampion/cskill-agents/withheld-max-output-token-errors","sourceUrl":"https://github.com/ychampion/cskill-agents/tree/main/skills/withheld-max-output-token-errors","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:40.237Z","lastSeenAt":"2026-04-22T00:56:58.780Z"}],"details":{"listingId":"f98158bb-378d-4c71-8b91-d7297bf44ab2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ychampion","slug":"withheld-max-output-token-errors","github":{"repo":"ychampion/cskill-agents","stars":34,"topics":["agent-skills","ai-agents","cli","coding-agents","context-engineering","developer-tools","mcp","multi-agent","terminal-ui"],"license":"mit","html_url":"https://github.com/ychampion/cskill-agents","pushed_at":"2026-04-04T14:13:23Z","description":"Agent skills for coding CLIs, multi-agent runtimes, context engines, MCP extensions, and terminal tooling. Instead of using claude code's source code, give your agent skills to create your own!","skill_md_sha":"9bf94aa67503398392c1ca78a92c08efbf6f5ac7","skill_md_path":"skills/withheld-max-output-token-errors/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ychampion/cskill-agents/tree/main/skills/withheld-max-output-token-errors"},"layout":"multi","source":"github","category":"cskill-agents","frontmatter":{"name":"withheld-max-output-token-errors","description":"Delay surfacing max-output-token failures until the recovery loop completes, then emit sanitized tool_result errors."},"skills_sh_url":"https://skills.sh/ychampion/cskill-agents/withheld-max-output-token-errors"},"updatedAt":"2026-04-22T00:56:58.780Z"}}