Module 3.1 — Running the audit-ablacao skill

🔍 Know what the skill does and what it never does

audit-ablacao and a skill — a procedure file that you keep in a folder and Claude Code loads when you call it by name or when its description matches your request. What this skill does: reads your CLAUDE.md (the project-level and global ones, in ~/.claude/CLAUDE.md), your other skills, the hooks (commands that Claude Code triggers automatically at certain times, before or after a tool runs) and the settings.json (Claude Code’s own configuration file: permissions, environment variables, hooks). Then it classifies each instruction, decides what to do with it, and delivers a 10-section report.

What it never does: edit, move, delete, overwrite config, or commit. That's intentional, not a limitation. An audit that starts making changes is an audit you can't trust — you lose the chance to disagree before the damage, and you lose the baseline for measuring whether the cut was good. Here, applying changes is a separate request from you, in another session.

🆕 Four words before you continue

Skill: file SKILL.md with a named procedure, loaded on demand by the agent.
Hook: command that Claude Code runs automatically in response to an event (before/after a tool, when ending the session).
settings.json: harness config—permissions, environment variables, and hook registration.
Trigger: the skill description sentences that make the agent decide to load it without you calling it by name.

✓ What the skill does

✓Read CLAUDE.md of the project and the global one
✓Read the skills, the hooks, and the settings.json
✓Classifies each instruction (context, guardrail, criterion, verification, micromanagement, redundancy, legacy…)
✓Decide: KEEP · SIMPLIFY · MOVE · MERGE · TEST · REMOVE
✓Audit skills one by one
✓Delivers the 10-section report

✗ What it never does

✗Edit any config file
✗Move or rename skills
✗Delete lines from your CLAUDE.md
✗Overwrite settings.json or hooks
✗Run git, commit or push anything
✗Comment on a file it couldn't read

What to look at: the solid arrows go all the way to the report—that’s the path the skill follows. The last arrow is dashed and crossed out with an X: applying is not part of its job. Also notice that the left column says “configuration (unchanged)”: the files go in and come out exactly the same.

Neighboring area: don't confuse the two

memory-audit

Takes care of the memory saved from the session: what was recorded, what is noise, what should be forgotten.

audit-ablacao

Takes care of the configuration of the agent: CLAUDE.md— skills, hooks, settings.json.

📦 Install the skill

Install a skill and copy a file to a folder. Nothing else. Two options: global (applies to all your projects, lives in ~/.claude/skills/) or per project (applies only there, stays in .claude/skills/ within the repository). Choose one of the two blocks below and run it in the terminal.

Path A — global installation

Available in any project you open with Claude Code.

git clone https://github.com/inematds/audit-ablacaocc.git
mkdir -p ~/.claude/skills/audit-ablacao
cp audit-ablacaocc/SKILL.md ~/.claude/skills/audit-ablacao/SKILL.md

Path B — project-level installation

Run it from the project folder. Replace <caminho> by where you cloned the repository.

mkdir -p .claude/skills/audit-ablacao
cp <caminho>/audit-ablacaocc/SKILL.md .claude/skills/audit-ablacao/SKILL.md

Verify that you installed it

Two checks: the file exists on disk, and the agent can see the skill.

# 1. o arquivo esta no lugar?
ls ~/.claude/skills/audit-ablacao/
# esperado: SKILL.md

# 2. o cabecalho da skill esta legivel?
head -4 ~/.claude/skills/audit-ablacao/SKILL.md
# esperado: uma linha "name: audit-ablacao"

Step 3: restart the Claude Code session. Skills are read at startup — until you restart, the skill exists on disk but not for the agent. After restarting, audit-ablacao should appear in the list of available skills.

💡 Global or per project? The practical difference

The project skill versioned alongside the code: it travels with the repository, goes into the pull request, and a colleague reviews the procedure like any other file. And it doesn’t spill over into your other projects — it’s no longer another line competing for attention where it doesn’t belong.

The global one, convenient for the tool you use everywhere. Simple rule: team procedure goes in the project, personal tool goes in the global config.

🎯 Choose the right scope

Scope and the set of files you want the skill to audit. If you don't specify, it asks—and the answer changes the report's quality more than any other choice in this module. Three scopes worth considering, each with its own moment:

Scope	Where it lives	When to run
Global	`~/.claude/`	Every ~6 months, especially with a major model release
One project	`./CLAUDE.md` + `./.claude/`	When the `CLAUDE.md` of it exceeds ~150 lines
A set of skills	Some folders in `skills/`	When 3+ skills compete for the same trigger

Why not audit everything at once? Because the cost shows up in the report, not in your time. A broad scope means lots of instructions read with little attention per instruction: the tables get shallow, the “How to test” column becomes generic, and the Top 10 mixes things from contexts that aren’t comparable. A narrow scope does the opposite — each recommendation comes with a cited excerpt, a named risk, and a test you can run today.

✓ Well-chosen scope

✓"Audit only the CLAUDE.md global" — one file, analyze it line by line
✓"Audit the 4 video skills in this project" — a clearly bounded scope
✓One scope per session, one report per scope

✗ Scope that ruins the report

✗"Audit everything" — global + 12 projects + 40 skills in one pass
✗Vague scope ("my config") that forces the skill to guess what to read
✗Mixing two projects: the identified redundancies don't actually exist

📑 Read the 10-section report

The report has a fixed order, and that order makes an argument: it starts with the diagnosis, moves through the evidence, reaches the proposal, and ends with the test plan. Reading it in order means following the reasoning. Each section asks something of you — below, what and e.

What to look at: the steps rise across four bands. The first two bands (sections 1 to 5) look at what exists; the last two (6 to 10) propose and prove. The spotlight stays on step 10 because that’s where your work list comes from — but it only has value if the lower steps are filled with cited excerpts.

Executive summary — the 5 biggest problems

It asks you to decide whether these 5 are really your problems. If none sound familiar, the scope was wrong.

Metrics — instructions analyzed, count by decision, estimated % reduction

It asks you to check whether the number of instructions analyzed matches the actual size of what you asked it to read. Too low a number = partial reading.

Problems by file — File | Problem | Severity | Recommendation | Rationale

It asks you to check whether the reason is an argument, not an adjective. "Verbose" isn't a reason; "duplicates rule X from file Y" is.

Candidates for removal — Excerpt | File | Reason | Risk | How to test

The most important section. It asks you to open the file and check the passage. Without the "How to test" column, the report is incomplete — removing it without testing is a gamble.

Redundancies and conflicts

It asks you to decide which copy stays. An unresolved conflict still leaves the model to choose on its own — and you won't know which one.

Skills — Skill | Current function | Diagnosis | Recommendation | Estimated reduction

It asks you to recognize the function described. If the "current function" isn't what you use the skill for, its description is misleading — and so is its trigger.

`CLAUDE.md` proposed — complete minimum version

It asks you to read it as a draft, not an order. It comes in a code block and is a proposal — nothing has been applied to your file.

Proposed skills — reduced versions of the ones that remain

It asks you to verify that the procedure is still executable after the cut. A streamlined skill that lost an essential step isn't a gain.

Ablation plan — A (current) / B (simplified) / C (minimal)

It asks you to recognize the proposed 5 to 10 tasks as tasks real of your project. A hypothetical task proves nothing. And that's the subject of Module 4.1.

Top 10 changes — by expected impact ÷ risk

It asks you to check your work queue. If an item appears here without appearing in any previous section, it came out of nowhere — be suspicious.

⚠️ The skill doesn’t apply anything—don’t ask it to edit

Finished reading the report and feel like saying "now apply the Top 10 for me"? Don’t. Applying changes in the same session as the audit mixes diagnosis with execution: you lose version A (the original, intact config) that the ablation plan needs as a baseline, and you lose the chance to disagree item by item. Make changes in another session, with the saved report open beside you.

🧩 Audit skill by skill

A standalone instruction has 6 possible decisions (KEEP · SIMPLIFY · MOVE · MERGE · TEST · REMOVE). A skill has 7, because a skill is a unit with boundaries: you can split it, merge it, or change the moment where it is loaded. This last possibility— load-on-demand, load only when the task calls for it instead of keeping it in context all the time—and the one that frees up the most space without losing anything.

Decision	Means	Typical sign
KEEP	Keep as is	Solves a recurring problem and has no dead weight
SIMPLIFY	Keep, but shorten	Good criteria buried in too many steps and examples
MERGE	Merge with another	Two skills competing for the same trigger and saying almost the same thing
SPLIT	Becomes two	A file with two procedures that are never used together
LOAD-ON-DEMAND	Only loads when requested	Useful, but rare — it doesn't need to cost context on the other 90% of tasks
CONVERT-TO-CONTEXT	Becomes two lines in the `CLAUDE.md`	There is no procedure there, just a fact that needs to always be available
DELETE-CANDIDATE	Candidate for removal	Teaches generic reasoning the model already does on its own

The decisions above don't come out of nowhere. They follow from seven questions the skill asks for each file—and that you can ask yourself, by reading any of your skills:

The questions that decide

1.Does it need to exist?
2.What problem recurring does it solve it? (one time only, not recurring)
3.Which parts are context, which are procedure, and which are micromanagement?
4.Could this fit in a short instruction?
5.Should it load only on demand?
6.Can it be split, or merged with something else?
7.Do these include things the model already does on its own?

💡 Practical tip

Question 3 is the one that yields the most. Take one of your skills and mark each paragraph with one of three letters: C (context—a fact the model can’t infer), P (procedure—a genuinely repeatable step), or M (micromanagement—you directing how it thinks). Every M is an immediate candidate to become an exit criterion. The skill does exactly that, but across the entire file.

🧪 Run and check 3 removals

Time to run it. Call it directly by name, or trigger it with natural language—the difference is that a direct call eliminates the lottery: you don't depend on the skill description matching your phrasing. Ask for the output in a file .md new; a 10-section report in chat scrolls off the screen before you finish checking it.

How to call it

# chamada direta (recomendada)
/audit-ablacao

# por gatilho, em linguagem natural
faz uma auditoria de ablacao do meu CLAUDE.md global
audita as skills deste projeto, meu prompt ta inchado
o que da pra remover da minha config sem quebrar nada?

# pedindo a saida em arquivo (faca isso)
/audit-ablacao — escopo: ~/.claude/CLAUDE.md e ~/.claude/skills/.
Salve o relatorio completo, com as 10 secoes, num arquivo .md NOVO
no diretorio de trabalho. Nao edite nenhum arquivo de config.

✓ A report you accept

✓Every recommendation cites a file and passage
✓Every meaningful removal comes with the risk explained
✓The “How to test” column is filled in with a test you can run
✓Where evidence is lacking, the decision is TEST, not KEEP or REMOVE

✗ Report you return

✗Diagnosis based on an assumption about a file it didn’t read
✗"Too verbose, cut it" without pointing to the passage
✗Treating a security guardrail cut as a concision gain
✗70% reduction celebrated without any test plan

💡 Shorter isn’t always better

The goal isn’t the biggest percentage reduction. It’s quality + autonomy + verifiability ÷ complexity. Context that the model can’t infer on its own—project identity, file paths, sources of truth, branding, security, compliance, interface contracts—doesn’t go into the cut queue just because it’s long. If the report suggests removing anything in this group, the right answer is “no,” not “great, another 8%.”

🎯 Exercise: audit the auditor

Objective: move beyond passive reading. You’ll take 3 REMOVE recommendations from your own report and check them one by one in the file, with the relevant passage open in front of you.

1. Rode a skill no escopo escolhido, salvando em relatorio-ablacao.md
2. Abra a secao 4 (Candidatas a remocao) e escolha 3 linhas
3. Para cada uma:
   - abra o arquivo citado no trecho
   - confirme que o trecho existe MESMO, e no lugar indicado
   - anote arquivo:linha
   - de o veredito: CONCORDO / DISCORDO / MUDA PARA TEST
   - escreva uma frase dizendo por que

Formato da anotacao:
  ~/.claude/CLAUDE.md:42 — MUDA PARA TEST
  "o risco descrito e real, mas nao existe teste proposto;
   quero ver o modelo falhar sem isso antes de apagar"

Exit criterion: a file .md saved with the complete report in all 10 sections, plus 3 written verdicts, each pointing to arquivo:linha. If you couldn’t locate the passage for any of the 3, that’s a finding: the skill made a claim about something it didn’t read carefully — and that line becomes DISAGREE right away.

Quick check (doesn't block anything): the report has a line in section 4 recommending REMOVE for a paragraph from your CLAUDE.md, with the reason and risk filled in—but the “How to test” column is empty. What should you do?

📌 Module Summary

✓

The skill reads, classifies, and reports—and stops there — never edits, moves, deletes, overwrites, or commits. And that's by design.

✓

Install and copy a file — global in ~/.claude/skills/, or by project in .claude/skills/; then restart the session.

✓

Narrow scope for a better report — global every ~6 months, projects over ~150 lines, skills when 3+ compete for the same trigger.

✓

10 sections, each demanding something from you — and section 4 without "How to test" means the report is incomplete.

✓

Skill has 7 decisions — KEEP, SIMPLIFY, MERGE, SPLIT, LOAD-ON-DEMAND, CONVERT-TO-CONTEXT, DELETE-CANDIDATE.

✓

It covers the skill — quoted passage, risk explained, no assumptions about unread files; when in doubt, TEST.

Next Module:

3.2 — From the report to the cuts: turn the Top 10 into a sequence of actionable changes without losing the baseline.

← Back to Track Next Module →