Guide · Agent skill
How to use the Bitter Lesson Engineering agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
BitterLessonEngineering is an agent skill that reviews a set of AI instructions, such as a CLAUDE.md file or other rule files, and asks whether a smarter model would still need each rule. This guide explains what the skill makes the agent do, how to install it, how to trigger it with plain requests, and what to check before accepting its suggestions. By the end you will be able to run a review and decide which suggested cuts to approve.
Bitter Lesson Engineeringdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Download the ZIP. Get the BitterLessonEngineering ZIP from this page. The skill folder is named BitterLessonEngineering.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. If you use the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill there.
- 4Ask for an audit in plain words. Say something like 'quick check this file' or 'audit setup' with the instruction file or rules you want reviewed.
- 5Review the verdicts. Read each rule's CUT, SHARPEN, MERGE or KEEP label and its reason before deciding anything.
- 6Approve changes deliberately. The skill does not change files until you approve the trimmed versions, so approve only the cuts you have checked.
What the Bitter Lesson Engineering skill does
The skill audits instruction sets for over-prompting. Each rule is sorted by kind first, then checked against a set of questions, including whether Claude already does the thing by default, whether two rules contradict each other, and whether a rule is just a step-by-step method for the model to follow.
Every rule gets one classification from CUT to KEEP, with a one-line reason. For a full audit the agent also estimates how many lines and tokens a trimmed setup would save. The skill is built on the test 'Would a smarter model make this unnecessary?'. Rules that fail that test are treated as scaffolding and become candidates for cutting.
- Preferences, safety gates, tool contracts and output-format contracts are kept.
- Step-by-step reasoning choreography is usually cut or rewritten as the outcome it protects.
- Contradictions and duplicate rules are flagged so you can keep one version.
Install the skill from the ZIP or the Claude apps
Download the BitterLessonEngineering ZIP from this page. To use it with Claude Code, unzip it into your user skills folder at ~/.claude/skills/ so it is available in every project. To limit it to one project, unzip it into that project's .claude/skills/ folder instead.
If you use the Claude apps, you can upload the skill under Settings, then Capabilities, then Skills, rather than placing files on disk.
- User-wide install: ~/.claude/skills/
- Single-project install: the .claude/skills/ folder inside the project
- Claude apps: Settings → Capabilities → Skills
How to trigger the skill with natural requests
You do not need special syntax. The skill's description lists the phrases that should activate it, so ask for an audit in ordinary words. Phrases such as 'audit setup', 'trim instructions', 'clean up CLAUDE.md', 'find dead weight' and 'over-prompting' all match its trigger list. The term 'bitter lesson' and the abbreviation BLE also work.
The skill has two modes. A full audit covers all force-loaded instructions and is started by requests like 'full audit' or 'check all rules'. A QuickCheck covers one file or a set of rules and is started by 'quick check' or 'check this file'.
- Full audit triggers: 'audit setup', 'full audit', 'check all rules'
- QuickCheck triggers: 'quick check', 'check this file', 'check these rules'
Examples of useful requests
Point the agent at a single file when you want a fast check. For example, ask it to quick check your CLAUDE.md, or paste rules inline and ask it to check these rules. The agent then reports each rule with its verdict and reason.
For a larger setup with many instruction files, ask for a full audit. Because the report covers every force-loaded instruction source, check that the scope it states matches the files you expected it to read.
- 'Quick check this file: CLAUDE.md'
- 'Check these rules for over-prompting' followed by the pasted text
- 'Run a full audit of my setup and tell me how many lines I could save'
- 'Clean up CLAUDE.md, but keep anything that protects a deploy approval'
What the skill needs and what it does not do
The skill needs an AI agent that can read SKILL.md skill folders, such as Claude Code. It also needs access to the instruction files you want audited. The skill refers to a LifeOS doctrine file, but that full doctrine is not included with the skill, so the review works from the files you give it and the skill text.
The skill does not run scripts and does not use the network. It does not change any of your files until you approve the proposed trimmed versions.
- Runs scripts: no
- Uses network: no
- Edits files only after you approve the trimmed versions
Safety notes before accepting cuts
A CUT recommendation can remove a rule that is doing real work. The skill's own evaluation notes say the main failure to watch for is a CUT or MERGE that removes a required safety, tool, or output contract. Rules that encode approvals, destructive-operation guards or required deliverable formats should be reviewed by a person before any cut.
Do not use the skill to audit instructions where nobody reviews the cuts and the rules guard real safety or approval steps.
- Read each CUT reason before approving it.
- Be extra careful with approval steps, destructive-operation guards and output formats.
- Keep a copy of the original files so you can restore anything you removed.
Tips for better results
Run a QuickCheck on one file first to see how the verdicts read before running a full audit. Compare the rule count and verdict counts in the report with what you expect from your files. Pay attention to rules that restate default behavior or use vague wording such as 'be more natural', since the skill flags these for cutting or sharpening.
Use the skill for the instruction files you maintain. For checking the logic of an idea or argument, use the RedTeam skill instead, because this skill is not designed for that job.
- Start with QuickCheck on a single file.
- Check that the report's scope matches the files you meant to audit.
- Use RedTeam for logical attacks on ideas.
What people use it for
- Trimming a long CLAUDE.md file that has grown over time with repeated or outdated rules.
- Finding contradictions between rules in the same file and in other instruction files.
- Checking a single instruction file quickly before editing it.
- Reviewing an agent setup with a structured report before a team edits its rules.
- Estimating how many lines and tokens a trimmed setup would save.
Frequently asked questions
How do I install the Bitter Lesson Engineering skill?
Download the BitterLessonEngineering ZIP from this page and unzip it into ~/.claude/skills/ to use it in every project, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
What do I need to run it?
You need an AI agent that can read SKILL.md skill folders, such as Claude Code, and access to the instruction files you want audited. The skill refers to a LifeOS doctrine file, but that doctrine is not included in the provided files.
Is the Bitter Lesson Engineering skill free?
The skill is listed under the MIT licence. Check the licence file in the source repository for the full terms before you reuse or modify it.
Does the skill change my CLAUDE.md file automatically?
No. The skill does not change any files until you approve the proposed trimmed versions. You should still read each CUT reason before approving, especially for rules that guard approvals or safety steps.
Does the skill run scripts or use the internet?
No. The skill does not run scripts and does not use the network, according to its documented requirements.
How is this different from the RedTeam skill?
Bitter Lesson Engineering audits instruction files for over-prompting, redundancy and contradictions. The RedTeam skill is the one meant for attacking the logical flaws in ideas and arguments, so use that for an argument check instead.
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 this skill if you maintain long AI instruction files or agent setups and want a structured review that finds dead weight, duplicates and contradictions before you edit. Pick something else if you need to check the logic of an argument, or if your instructions encode approval or safety steps that nobody reviews before cuts are accepted.
Download the skill