About this project
Reasoning Skill is a set of markdown files you add to Claude as a skill. Out of the box, Claude tends to give the most common answer to the most common version of a question. This skill replaces that habit with a fixed routine run before every non-trivial reply. The routine: work out who is asking and what they really need, audit the assumptions hiding in the answer, break the problem down to its basics, and look for a route around any limitation instead of just reporting it. Claude then argues against its own answer before sending it. It also covers the awkward cases: long conversations that have been summarized, when to ask a clarifying question, how to hold or change position under pushback, how to admit what it doesn’t know, and how to run web searches from your real goal instead of your literal words. It ships with a catalogue of known reasoning failures, each with a fix. Built to stay on for every conversation, not for simple factual questions.
Reasoning Skill
A structured reasoning skill for Claude. Before any non-trivial answer, Claude works through a fixed set of checks: who is asking, what they actually need, what is being assumed, and whether the first answer survives a challenge.
Core belief: nothing is impossible unless the laws of physics say so. Everything else is undone, undocumented, or waiting for the right approach.
Install
- Download the zip and unzip it. The folder must have SKILL.md at its top level.
- Add it to Claude as a skill:
- Claude app / claude.ai: zip the folder (SKILL.md at the root of the zip) and upload it under Settings → Capabilities → Skills.
- Claude Code: copy the folder to ~/.claude/skills/reasoning/ (all projects) or .claude/skills/reasoning/ (one project).
- Keep it enabled. It's designed to be always on.
SKILL.md is the entry point. It tells Claude which files to read and in what order, so keep the folder structure as is.
What's inside
- SKILL.md: entry point and read order
- PRINCIPLES.md: core rules that override default behaviour
- FLAWS.md: documented reasoning failures, each with a fix
- CONTEXT.md: who is asking and what they need
- SEARCH.md: web search driven by the goal, not keywords
- behavior/: ASSUMPTIONS, COMPACTION, PUSHBACK, QUESTIONING
- thinking/: FIRST_PRINCIPLES, WALLS, CONNECTIONS
- self/: INTROSPECTION, HUMILITY
How it runs
Applied in this order before a non-trivial reply:
- CONTEXT: who is asking and what they need
- PRINCIPLES: the core reasoning rules
- ASSUMPTIONS: challenge what's taken for granted
- COMPACTION: is the record complete?
- FIRST_PRINCIPLES: break the problem to its root
- WALLS: find a way around any limitation
- CONNECTIONS: look across domains
- INTROSPECTION: challenge the answer before sending
When web search is involved, SEARCH.md applies too.
Core principles
- The person came here last. They've already tried the obvious. Start where their knowledge ends.
- The goal isn't the request. Find the real goal behind what was asked.
- Context isn't optional. Location, resources, tools and skill level decide whether an answer is usable.
- Walls are information. A limitation blocks one path, not the destination.
- Certainty is a signal to check harder.
- Visible isn't complete. After a summary, conclusions without visible reasoning are claims to verify.
Failure modes it targets
| Failure | Fix |
|---|---|
| Treating undocumented as impossible | Ask why the limit exists first |
| Reporting a wall without trying to get round it | Find at least one alternative first |
| Answering the literal request, not the goal | Identify the goal first |
| Listing options without filtering them | Filter against the person's real constraints |
| Changing position under social pressure | Change only when the logic changes |
| Assuming Western infrastructure and buying power | Start from realistic local constraints |
| Trusting the first pattern-matched answer | Challenge it before delivering |
| Staying inside the question's domain | Search other domains before giving up |
| Trusting a compacted record as the full one | Verify conclusions with no visible reasoning |
Search behaviour
- Starts from the underlying goal, not the literal phrasing.
- Layered: broad, specific, validation, alternatives.
- Results are filtered through the person's context.
- Failures and known limits are searched alongside solutions.
- Default range is 2015 to present, favouring recent sources.
- If every search fails, Claude reasons about what might exist even if undocumented.
When it matters most
- A problem is called impossible or has no obvious answer.
- The user has already tried the standard approaches.
- The request is technical and specific to their setup.
- The user is resource-constrained.
Not for simple factual questions where context doesn't change the answer.
Customising
Each file is plain markdown. Edit the rules, add a failure to FLAWS.md, or add a file and list it in SKILL.md's read order. Keep SKILL.md's front matter (name, description) intact, since the description tells Claude when to use the skill.
Source: https://github.com/Firekid-is-him/Reasoning-Skill-Claude