handling-failures skill (riekelt): no silent error swallows

Makes Claude log and rethrow, return a typed failure, or enter a documented degraded mode on every error path.

Installs: 20.3K; on skills.sh
Stars: 7; on GitHub
Updated: Sep 2026; last repo commit

handling-failures sets one contract for every error path Claude writes or touches. It must log at WARN or ERROR and rethrow, log and return a typed failure the caller has to handle, or log and enter a documented degraded mode. It forbids bare catch-and-continue, catch-and-return-default and fallbacks that hide a failed primary. It fires on any catch block, fallback, default value, retry or degraded mode, in any language, and names principal-engineering as required background.

Good for

Developers who want errors surfaced instead of hidden by defaults
Reviewers who want a clear rule for flagging catch-and-continue
Teams running services where a healthy-looking wrong answer is worse than a crash

Install handling-failures

Claude Code

Copy this prompt.

Install the handling-failures skill in Claude Code. Run this command:

/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 11 skills in the repo, plus one agent (change-verifier) and two commands (/verify and /preflight), counted from the git tree. handling-failures names principal-engineering as required background, so the skills CLI and folder routes below install both. There is no Claude app upload route: the README documents only the Claude Code plugin and the other-agents routes.

From the project README. Source.

What's in the skill

When it loads

Use when writing or touching any error path, catch block, fallback, default value, retry, or degraded mode - in any language, any repo. Encodes the no-silent-swallows contract and the fail-loud discipline. Use whenever an exception is about to be caught, a null is about to get a default, or a failure could pass unnoticed, even if the goal is "just make it not crash".

Sections in SKILL.md

Overview
The contract
Corollaries
Touching existing swallows
Common mistakes

Key facts

Author: riekelt (named as author in the plugin manifest)
License: MIT per the README and plugin.json; the repo has no LICENSE file and GitHub shows none
Installs on skills.sh: 20,332 (Nov 2, 2026)
GitHub stars: 7 for the whole riekelt/principal-engineer repo (Nov 2, 2026)
Last repo commit: Sep 11, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (counted from the git tree)
Part of: The principal-engineer plugin: 11 skills, 1 agent and 2 commands (counted from the git tree)
Needs: The principal-engineering skill, named as required background in SKILL.md
Works in: Claude Code via the plugin; other agents via a plugin loader or symlinked skill folders, as the README describes

What it includes

Log and rethrow, return a typed failure, or enter a documented degraded mode
Every catch and failure path does exactly one of the three, and all three are loud.
Write · The three-way contract
Bans bare catch-and-continue, default-return masks and hiding fallbacks
A fallback is acceptable only when the absence is also surfaced loudly elsewhere.
Write · Forbidden patterns
Fail loud on missing entries, bound retries, make replays idempotent
The seven: missing required entries fail loud, error states are visible, remediation text is specific, retries are bounded, replays are idempotent, degraded modes have a bound, and logs, counters and alerts ship with the fix.
Write · Seven corollaries
Fix a swallow in code you edit, or flag it as owed
Leaving an existing swallow silently is endorsing it. In review a new silent swallow is an automatic BLOCKER; an old one you touched and left unflagged is a WARNING.
Write · Touching existing swallows

From the official docs

Permissions

Low risk

handling-failures is instructions for Claude and the plugin route adds an agent and two commands. Our advice: review the diff after each session and keep your tool's permission prompts on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can change error handling beside the lines you named
SKILL.md says an existing swallow in code Claude is editing gets fixed or flagged. Review the diff for edits you did not ask for. github.com
The plugin route adds an agent that can run shell commands
change-verifier lists the tools Read, Glob, Grep and Bash, and the plugin adds the /verify and /preflight commands. The repo tree has no hooks or MCP config files. Use the skills CLI route to install only this skill. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Sign-in and keys	SKILL.md names no account, key or token.
Scopes	Claude edits error paths, fallbacks and retries in your code The plugin route also installs 10 other skills, one agent and two commands

Questions

What does handling-failures do?

It gives Claude one rule for errors: every failure path logs and then rethrows, returns a typed failure the caller must handle, or enters a documented degraded mode. Silent catch-and-continue is banned.

How do I install it?

Use the install box at the top. The skills CLI and folder routes add principal-engineering as well, because this skill names it as required background. The plugin route installs all eleven skills.

Does it ban every fallback?

No. SKILL.md says a fallback is acceptable only when the absence is also surfaced loudly elsewhere. A fallback that hides the fact that the primary failed is forbidden.

Will it change error handling I did not ask about?

It can. SKILL.md says code Claude is editing that already swallows an error should be fixed as part of the work or flagged as owed. Review the diff for changes beside the lines you named.

Does it work in the Claude app or Codex?

The README documents the Claude Code plugin and, for other agents, a plugin loader pointed at plugins/principal-engineer/ or symlinked skill folders. It documents no Claude app upload route.

Is it safe to install?

The skill folder bundles no scripts. It changes how Claude writes error paths in your code, so check the diff. The plugin route also adds an agent, covered under "Watch out for".

Information

updated Nov 2, 2026

Repository: riekelt/principal-engineer
Folder: plugins/principal-engineer/skills/handling-failures

riekelt/principal-engineer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

handling-failures SKILL.md · github.com
principal-engineering SKILL.md · github.com
README · github.com
plugin.json · github.com
change-verifier agent · github.com