handling-failures — Claude Code skill: no silent error swallows
handling-failures — a skill that forces AI assistants to write honest error paths. Every failure either gets logged and rethrown, returns a typed error, or shifts the system into an explicit degraded mode.
no license 25,500 installs ★ 6 updated 2026-09-11
npx skills add riekelt/principal-engineer --skill handling-failures -a claude-codeWhat handling-failures does
The core contract is simple: a failure path does one of three things. Log at WARN or ERROR and rethrow. Log and return a typed failure the caller must handle. Or log and enter a documented degraded mode with something observable marking the state. Bare catch-and-continue, returning an empty list or null, and ?? fallbacks that hide a failed primary are all forbidden.
Several rules follow from this. A missing required entry in a registry or config is a build or startup failure, never a quiet default. Retries of side-effecting operations have to be idempotent. Degraded modes need a named, operator-tunable threshold where degradation becomes abort. Observability ships with the fix — the log line, counter, and alert are part of the minimum.
This skill depends on the principal-engineering skill from the same repository. When you edit code that already swallows errors, the skill demands either fixing it in the same task or flagging it as owed debt with a note on what it hides. A new silent swallow in review is an automatic blocker.
What it helps with
- catch blocks that log nothing and keep running
- defaulting to null or an empty list on failure
- fallbacks that mask a broken primary source
- degraded modes with no documented stop threshold
- replaying non-idempotent side effects
Example prompts for the agent
- This catch swallows an exception — rewrite it to log at ERROR and rethrow.
- Show me how to make this
??fallback surface the primary source failure. - Review this file for silent error swallows and propose fixes.
How to install handling-failures
1Skills CLI (Vercel)
npx skills add riekelt/principal-engineer --skill handling-failures -a claude-code2Manually: put the files in place
~/.claude/skills/handling-failures/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/handling-failures/
1Skills CLI (Vercel)
npx skills add riekelt/principal-engineer --skill handling-failures -a codex2Manually: put the files in place
.agents/skills/handling-failures/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add riekelt/principal-engineer --skill handling-failures -a cursor2Manually: put the files in place
.cursor/skills/handling-failures/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install riekelt/principal-engineer plugins/principal-engineer/skills/handling-failures2Manually: put the files in place
.github/skills/handling-failures/SKILL.md1Skills CLI (Vercel)
npx skills add riekelt/principal-engineer --skill handling-failures -a gemini-cli2Platform CLI
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/handling-failuresManually: put the files in place
.devin/skills/handling-failures/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add riekelt/principal-engineer --skill handling-failures -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about handling-failures
How do I install handling-failures in Claude Code?
Run npx skills add riekelt/principal-engineer --skill handling-failures -a claude-code. The skill lands in ~/.claude/skills/handling-failures/SKILL.md.
What does handling-failures do?
It sets rules for every error path: catch blocks, fallbacks, default values, retries, degraded modes. A failure must be loud — logged and rethrown, returned as a typed error, or handled through a documented degraded mode.
What does the skill depend on?
It requires the principal-engineering skill from the same riekelt/principal-engineer repository.