Guide · Agent skill
How to use the First Principles Reasoning agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
FirstPrinciples is an agent skill: a set of instructions and reference files that a Claude agent loads when you ask for certain kinds of reasoning. It makes the agent break a problem into its basic parts, sort every limit into hard constraint, soft constraint or assumption, and then design a solution from only the parts that cannot change. This guide shows you how to install it, how to trigger it with ordinary requests, and what it does and does not do.
First Principles Reasoningdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Download the ZIP. Get the FirstPrinciples ZIP from the directory page.
- 2Unzip into a skills folder. Place the FirstPrinciples folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Ask in plain language. Use trigger words such as first principles, challenge assumptions or rebuild from scratch in your request.
- 5Review the constraint table. Check each HARD, SOFT or ASSUMPTION label and its evidence against what you know.
- 6Use the rebuilt solution as input. Treat the reconstruction as a design proposal to test, not as a final decision.
What the FirstPrinciples skill makes the agent do
Without the skill, an agent tends to reason by analogy: it looks at how similar problems are usually solved and copies that approach with small changes. The FirstPrinciples skill changes the method. The agent asks what the subject is actually made of, labels each limit as a physical law (hard), a policy or choice (soft), or an unproven belief (assumption), and then rebuilds the solution using only the hard constraints.
The work runs in three intents: Deconstruct (break the problem into parts and real values), Challenge (classify each constraint) and Reconstruct (build the solution). They can run in order as a full analysis or separately when you already have the input you need.
- Deconstruct: breaks a subject into constituent parts and real values, not market prices.
- Challenge: classifies each constraint as HARD, SOFT or ASSUMPTION, with the evidence for the label.
- Reconstruct: builds a solution from the fundamentals alone and compares it with the current approach.
- Output: a parts breakdown, a constraint table and a reconstructed solution, plus a key insight naming the limiting assumption.
Install the FirstPrinciples skill
Download the ZIP for the skill from the directory page. Unzip it into one of two places. For a personal install available to all your projects, put the skill folder inside ~/.claude/skills/. For a project-only install, put it inside the project's .claude/skills/ folder. The skill folder should contain SKILL.md and the Intents folder.
If you use the Claude apps instead, upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/FirstPrinciples/
- Project only: .claude/skills/FirstPrinciples/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need a special command. Ask in plain language, and use words that match the skill's trigger phrases such as first principles, fundamental truths, challenge assumptions, real constraint, rebuild from scratch, start over, physics first, question everything or reasoning by analogy. Naming the intent helps: say 'break it down' for Deconstruct, 'is that a real constraint' for Challenge, or 'start over from scratch' for Reconstruct.
A quick pass is also possible. If you only want a short answer, say so, and the skill is meant to return the irreducible job, the classification and the key insight in a few lines rather than the full template.
- "Is the requirement to keep this on REST a real constraint or just how we've always done it?"
- "Break down what a job scheduler is actually for, irreducibly."
- "We're stuck. Rebuild this data pipeline from scratch using first principles."
- "Quick inline pass: which of these limits are physics and which are policy?"
Examples of what you get back
A full run returns a combined report: Deconstruction (constituent parts and actual values), a Constraint Classification table with evidence and a challenge column, a Reconstruction (fundamental truths, optimal solution and a form-versus-function check), and a Key Insight in one sentence.
The skill's own examples show the pattern: asking what a model router is fundamentally for leads to Deconstruct, then Challenge, then Reconstruct, ending with the assumption that was limiting the current design.
- Parts breakdown of a subject, with the function stated as an outcome rather than a mechanism.
- Constraint table where each limit is marked HARD, SOFT or ASSUMPTION with its reason.
- A rebuilt solution built only from hard constraints, compared with the current approach.
What the skill needs and its safety notes
The source lists no requirements. The skill does not run scripts and does not use the network, according to its listing. It is analysis only: it is not meant to make the fix itself. A request to fix something is handled directly, not through this framework.
Its classifications are the agent's judgement. A label of 'hard' or 'assumption' can be wrong, so do not treat the output as authoritative where real evidence matters without review by someone with the relevant expertise.
- Requires: nothing listed in the source.
- Runs scripts: no. Uses network: no.
- Do not use it for simple implementation or bug-fix tasks.
- Do not use it for structural feedback-loop analysis; the description directs that to the SystemsThinking skill.
Tips for better results
Give the agent the real facts you have. The skill is designed to check each constraint against evidence, so supplying data, budgets or requirements gives it something to classify. Be clear about what you are optimizing, because the skill focuses on the function a thing serves rather than its traditional form.
You can also customise the skill. If the folder <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/FirstPrinciples/ exists, its PREFERENCES.md and other files override the defaults, where <configRoot> is $CLAUDE_CONFIG_DIR when set, otherwise ~/.claude.
- Name the outcome you want, for example 'pick the right model and effort for a piece of work'.
- Ask for the one assumption that was limiting the current approach.
- Keep requests for real redesigns; use a plain request for a routine fix.
What people use it for
- An architect asking whether a required interface is a real constraint or an inherited convention.
- An engineer stuck on a design who wants to question assumptions before accepting 'we can't do that'.
- A team planning a redesign that wants a fresh approach rather than incremental patches.
- A security reviewer testing which assumed boundaries in a system could be wrong.
Frequently asked questions
Is the FirstPrinciples skill free to use?
The source lists the licence as MIT. It does not state any price, so check the directory page for any further terms.
What does FirstPrinciples require to run?
The source lists no requirements. It does not run scripts and does not use the network, according to its listing.
How do I install the FirstPrinciples skill?
Download the ZIP and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What is the difference between FirstPrinciples and SystemsThinking?
FirstPrinciples breaks a problem into fundamental truths and classifies its constraints. The description says structural feedback-loop analysis belongs to the SystemsThinking skill, so use that one for feedback loops.
Why is the agent not fixing my bug with this skill?
The skill is for analysis, not implementation. The source says simple implementation or bug-fix tasks should be done directly rather than through this framework.
Can I trust the hard versus assumption labels?
Not without review. The labels are the agent's judgement and can be wrong, so have an expert check them where real evidence matters.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use FirstPrinciples when you suspect inherited conventions are limiting a design, or when you want to question assumptions before accepting a constraint. Pick something else for simple fixes, feedback-loop analysis (use SystemsThinking), or high-stakes decisions that need expert verification of the constraint labels.
Download the skill