How to use the Simplify agent skill safely

What the Simplify skill makes the agent do

Simplify works in three stages. First it surveys the target read-only, recording what the target is for and everything that calls or references it, including imports, hooks, settings, docs and tests. It then classifies each element as load-bearing, duplicate, dead, cruft or over-abstracted, with evidence for each label.

Next it proposes ranked cuts and holds them for your approval. Only after you approve the specific rows does it apply them, checking before-and-after parity so that nothing a dependent relies on breaks.

How to install Simplify

Download the Simplify ZIP from the page where you found this guide. Then choose one of the two install routes described in the source.

For a personal install, unzip the download into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder. Either way the skill's files, including SKILL.md, should sit inside the skills folder.

If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

How to trigger Simplify with a natural request

You do not need a special command. Describe what you want in plain words and include the target. The skill is triggered by requests such as 'simplify this', 'simplify this system', 'remove cruft', 'remove duplication', 'dedupe', 'dead code', 'clean this up', 'this has gotten bloated', 'too complicated', 'reduce complexity', 'consolidate', 'strip this down without breaking it' and 'what can we delete'.

A bare request such as 'simplify X' runs Survey and then Propose, and stops at the proposal so you can review it. If you only want the map, ask for a survey or say 'map this before we cut' or 'is this dead', which stops after the survey.

• Simplify a tool: 'simplify LIFEOS/TOOLS/ReferenceCheck.ts'
• Find unused code: 'is this dead'
• Approve cuts: 'y', or 'y, but skip 4' to leave out row 4

Understand the three stages: Survey, Propose and Apply

Survey is a read-only map. It states the target's purpose, taken from its ISA when one exists or otherwise derived from docs, callers and git history, and it lists each search that ran, including the ones that found nothing.

Propose ranks the changes. Each one names a move (delete, merge, inline, relocate or tighten), the exact text or code it touches, its estimated size saved, its risk, and what it preserves. Apply then lands only the approved rows, each approved group as its own commit, and reports the baseline pass counts before and after.

• Survey: maps the target and classifies every element
• Propose: ranks the cuts and waits for your yes
• Apply: makes the approved changes and checks parity

What Simplify needs and its safety notes

Simplify needs access to the target codebase and to its test suite or probes, because parity can only be shown by checks that already exist. It writes its records under LIFEOS/MEMORY/WORK/{slug}/simplify/, and the source assumes a LifeOS directory structure. According to the source, the skill runs no scripts and uses no network. It reads no config and needs no account or key.

Be aware that zero search hits do not prove code is dead. Many things are called by string, such as hook registrations in settings.json, launchd plists, workflow YAML, skill routing tables and dynamic imports. Simplify is designed to check these, but you should still review what it reports. If a file changes after its survey, the skill re-reads it before touching it.

• Needs: the target code, its tests or probes, and write access for its records
• Runs scripts: no
• Uses network: no
• Projects without tests or probes weaken the safety claim

Tips for getting good results

Give a specific target such as one file, one skill or one subsystem, rather than the whole machine. Smaller targets produce clearer surveys. Read the proposal before approving, and check that each row cites the survey finding it acts on.

Approve in small groups so each commit stays easy to review. If you want to keep a delete of irreplaceable content, approve it on its own. Use a different skill when your need is a different job, as described below.

• Always-on context files such as CLAUDE.md go to Trim, not Simplify
• Cleanup of only the current diff goes to /simplify
• Bug hunting goes to /code-review
• Harmony across many systems goes to Unify