no-workarounds — Claude Code skill: what it does, how to install
This skill examines fixes that conceal an error or its symptoms. Use it when a change looks like a workaround or the defect comes from outside your codebase.
npx skills add pedronauck/skills --skill no-workarounds -a claude-codeWhat no-workarounds does
The skill guides the agent to trace a symptom to the code or boundary responsible, address the cause, and check the result with an existing test or probe. It calls for context when reviewing diagnostic filters, caught errors, timed delays, and fallback paths: each deserves scrutiny, though none is automatically wrong. A related entry in references/workaround-catalog.md can help with the review.
For a defect outside the team’s control, the skill recommends containing an adapter at the boundary, recording the evidence and a removal condition, then protecting the affected behavior with existing checks. This review is not a required step for every bug fix. Project-mandated boundary validation and compatibility adapters should remain in place, so removing them just to silence a symptom would be the wrong fix.
What it helps with
- trace an error hidden by diagnostic filtering
- assess whether an error handler or fallback is justified
- fix a defect and verify the original symptom
- contain an external defect behind a boundary adapter
Example prompts for the agent
- Check whether this change fixes the cause or just hides the error.
- Review this fallback path and suggest a check for the original failure.
- An external dependency is failing. Show how to isolate it at the boundary and define when to remove the adapter.
How to install no-workarounds
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill no-workarounds -a claude-code2Manually: put the files in place
~/.claude/skills/no-workarounds/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/no-workarounds/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill no-workarounds -a codex2Manually: put the files in place
.agents/skills/no-workarounds/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill no-workarounds -a cursor2Manually: put the files in place
.cursor/skills/no-workarounds/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pedronauck/skills no-workarounds2Manually: put the files in place
.github/skills/no-workarounds/SKILL.md1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill no-workarounds -a gemini-cli2Platform CLI
gemini skills install https://github.com/pedronauck/skills --path skills/mine/no-workaroundsManually: put the files in place
.devin/skills/no-workarounds/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pedronauck/skills --skill no-workarounds -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 no-workarounds
How do I install no-workarounds in Claude Code?
Run npx skills add pedronauck/skills --skill no-workarounds -a claude-code. The skill file is at ~/.claude/skills/no-workarounds/SKILL.md.
What does no-workarounds do?
It helps assess whether a proposed change addresses the cause of a failure or merely masks it, then points to checks for the original behavior.
Should I use this skill for every bug fix?
No. It is meant for suspected workarounds and defects beyond the team’s control, rather than as a required step in routine fixes.
