My humanizer es en

my-humanizer-es-en — Humanizador definitivo ES/EN

Battle-tested pipeline that took a real academic article from 50% → 13% AI on Compilatio Magister+ across three iterations, without touching a single citation or datum. This skill encodes exactly what worked.

Core idea: modern detectors (Compilatio, Turnitin, GPTZero) are stylometric, not plagiarism-style. They flag rhythm and structure, not vocabulary. The win comes from breaking AI's uniform cadence — above all, the statement: elaboration colon habit and symmetric enumerations — and injecting real human burstiness.

---

0. When to use / what you get

Use when the user wants to lower an AI-detection score on a document, or fix the "blue" (AI) and "similarity" sections of a detector report.

Two entry modes — both fully supported:

• Report-driven (best): a detector PDF report + the document. Extract the highlighted passages (§4), rewrite only those, iterate. Most efficient; this is what got 13%.
• Blind (no report): only the document. Run the internal leak scan (§4b) to find the passages most likely to trip a detector, rewrite them with the rulebook (§5), measure metrics (§7), deliver. Slightly less surgical than report-driven, but works with nothing but the text.

If the user has a detector report, ask for it — it makes every pass cheaper and more precise. If they don't, or can't run the detector, go blind; never block on the report.

Non-negotiable constraints:

• Preserve the content core — every claim, number, %, date, and citation.
• Never alter the reference list. Similarity hits there are legitimate citation matches; changing an APA/IEEE entry is an error, not a fix.
• Preserve document structure — headings, paragraph count, styles.

---

1. Prerequisites (install once)

python3 -m pip install --quiet pymupdf pypdf defusedxml
# docx read/write uses only stdlib + unix zip/unzip. LibreOffice optional (render check).

pymupdf (fitz) is the key tool: it reads the highlight/underline fill colors in a detector PDF, which plain text extraction (pypdf/pdftotext) throws away.

---

2. Pipeline overview

extract text ─► (if report) parse highlights by color ─► classify passages
   ─► rewrite flagged prose (rulebook §5) ─► rebuild .docx (§6)
   ─► measure metrics (§7) ─► iterate on remaining flags (§8)

---

3. Read the document (.docx)

pandoc is often absent. Extract text directly from the XML — robust and dependency-free:

unzip -q -o input.docx -d unpacked/
find unpacked -type l -delete            # untrusted docx: strip symlinks

# scripts: quick paragraph dump
import re
x = open('unpacked/word/document.xml', encoding='utf-8').read()
paras = re.findall(r'<w:p\b.*?</w:p>', x, re.S)
for i, p in enumerate(paras):
    t = ''.join(re.findall(r'<w:t[^>]*>(.*?)</w:t>', p, re.S))
    if t.strip():
        print(i, t)

Note the paragraph index of every body block. Indices are the addressing scheme for surgical rewrites and stay stable as long as you don't add/remove paragraphs. Headings, abstract, keywords and the reference list are paragraphs too — know which is which.

---

4. Parse the detector report (the decisive step)

Detector PDFs underline/highlight suspect text in color. Compilatio uses a thin colored underline (~1.4pt rect) under each word:

• Blue #00beff = AI-detected passage → must be paraphrased/humanized.
• Green #cdf0ce / #58da5e = similarity to a source → only correct if it is in the body; in the reference list it is legitimate and left alone.

Run scripts/analyze_report.py report.pdf — it prints, per page, the exact text sitting under blue underlines (IA) and under green (similarity). Because the underline is a baseline strip, the script inflates each rect upward ~11pt and tests bbox intersection with each word.

Colors vary by tool/version. If nothing maps, dump the fill-color histogram first (the script does this with --colors) and identify the highlight color, then pass --blue RRGGBB.

Only rewrite passages the report actually flags. Leave clean passages untouched — re-touching them wastes effort and can introduce new patterns.

---

4b. Blind mode — internal leak scan (no report needed)

When there is no detector report, approximate one. Run:

python3 scripts/scan_leaks.py unpacked/ <body_indices>   # or --text file.txt

scan_leaks.py scores every sentence for stylometric AI tells (ES + EN) and ranks the worst offenders, each with the reason it was flagged:

• very long sentences (low burstiness),
• statement: elaboration colons and colon-introduced lists,
• symmetric enumerations / rule-of-three,
• negative parallelism (no solo… sino / not only… but),
• AI vocab (además, crucial, panorama, furthermore, delve, …),
• em/en dashes, participle tails (…-ando/-ing giving false depth).

Treat its output like a detector's blue highlights: rewrite the top-scoring sentences first (§5), re-run the scan, repeat until the flagged share and the §7 metrics look human. It is a heuristic proxy, not a detector — it finds candidates, it does not certify a score. Combine it with §7 metrics; when the two agree the text is clean, you are in good shape.

Reference point: after reaching 13% on Compilatio, the scan still marked ~16% of sentences — so aim to drive the flagged share down and the burstiness up, not to literally zero.

5. The humanization rulebook (what actually moved the score)

Apply to flagged prose only. Keep the register academic but let a real person show through. Ordered by impact:

5.1 Kill the colon "statement: elaboration" habit ⟵ highest impact

AI loves Claim: supporting detail. It's the single strongest tell in polished academic text. Target ≤ 3–4 colons in the entire body.

• Before: El hallazgo apunta al canal: hay herramientas que superan el 97 %...
• After: El hallazgo no apunta tanto a la tecnología. Apunta al canal. Ya hay herramientas que superan el 97 %...

5.2 Break symmetric enumerations

dos cosas:, tres frentes:, cuatro ejes:, el patrón es doble:, not only… but also…. Any "here are N balanced items" scaffolding reads as machine-planned. Dissolve into running prose or separate short sentences of uneven length. Never keep three parallel clauses in a row.

5.3 Maximize burstiness (sentence-length variance)

Humans write a 3-word sentence next to a 40-word one. AI clusters near the mean.

• Mix fragments (Ya se probó. Información, no trámite.) with long winding sentences.
• Targets that correlate with passing (measured): mean sentence length ~13–15 words, and lots of very short sentences pulling the distribution wide.
• Insert genuine questions where natural (¿Sabe el vecino a qué hora pasa?).

5.4 First person + stance

Where the text reports the authors' own work, use we/nosotros: aplicamos, pusimos en diálogo, lo que encontramos, we asked, we put X next to Y. Neutral third-person exposition is an AI signature.

5.5 Concrete, slightly messy detail

Replace abstract summaries with specific, imperfect images.

• Before: residuos amontonados en la vereda (tidy)
• After: Una funda que los perros abrieron de madrugada. Bolsas amontonadas esperando un camión que ya se fue.

5.6 Vary paragraph openings

Don't start every paragraph with a topic sentence. Open with a question, a fragment, a datum, an aside. Break the essay-template cadence.

5.7 Register-appropriate colloquialism (ES)

la plata, a los tumbos, le ponga el hombro, da la talla, sin maquillaje. Enough to sound human; not so much it breaks academic tone.

5.8 Full "Signs of AI writing" checklist (baked in — see §11)

This skill folds in the complete Wikipedia "Signs of AI writing" guidance (ES and EN). Remove/repair every one of these:

• Inflated significance / legacy talk (marca un hito, desempeña un papel crucial, testament to, pivotal moment).
• Promotional/peacock language (vibrante, rico en, robust, seamless, must-visit).
• Superficial -ing/-ando participle tails that fake depth.
• Vague attribution (los expertos creen, studies show, observers note).
• "Challenges and future prospects" filler sections.
• AI vocab clusters (además, crucial, panorama, subrayar, fomentar, furthermore, delve, leverage, underscore, landscape, tapestry).
• Copula avoidance (sirve como/serves as → es/is).
• Negative parallelism (no solo… sino, not only… but also).
• Rule of three (force groups of two or four, or dissolve).
• Forced synonym carousel; false-range "de X a Y / from X to Y".
• Em-dash overuse (—) → commas/parentheses.
• Bold overuse, inline-header bullet lists, Title Case headers, emojis, curly quotes.
• Collaboration/chatbot artifacts (¡claro!, hope this helps), knowledge- cutoff disclaimers, sycophantic tone, filler phrases, over-hedging, generic upbeat conclusions.

5.9 What you must NOT change

Citations (Autor, año), numbers, %, dates, times (07h00), proper nouns, the reference list, headings text, and the paragraph/section structure.

---

6. Rebuild the .docx (surgical, format-preserving)

Edit word/document.xml in place — never regenerate the doc (you'd lose styles, hanging indents, hyperlinks). For each target paragraph, collapse its runs and drop the new text into the first run so formatting is kept.

scripts/replace_paragraphs.py takes a JSON map {paragraph_index: "new text"} and does exactly this (handles multi-run paragraphs, XML-escapes, forces xml:space="preserve", validates well-formedness).

python3 scripts/replace_paragraphs.py unpacked/ edits.json
(cd unpacked && rm -f ../out.docx && zip -Xrq ../out.docx .)
# optional validation if the Anthropic docx skill is present:
python3 <docx-skill>/scripts/office/validate.py out.docx --original input.docx

Sanity check after every rebuild: paragraph count unchanged (e.g. 51 → 51) and the XML parses.

---

7. Measure before delivering

Run scripts/text_metrics.py unpacked/ <body_indices>:

Metric	AI-ish	Human target
Colons in body	20+	≤ 4
Mean sentence length	20–25 words	13–16
Sentence-length stdev	low vs mean	as high as reads naturally
Em-dashes	several	~0
Sentence count (same text)	fewer/longer	more/shorter

Real trajectory that reached 13%: colons 24 → 12 → 3, mean length 22.4 → 14.6 → 13.8 words.

---

8. Iterate (this is why it works)

You usually can't run the institutional detector yourself (Compilatio runs inside the user's LMS/Canvas). So:

1. Deliver a version, ask the user to submit it and return the new report PDF.
2. Re-run §4 on the new report — the blue set shrinks each round.
3. Rewrite only the still-blue paragraphs, harder (more §5.1/§5.2/§5.3).
4. Leave now-clean paragraphs frozen.
5. Repeat until the score is at target.

Version the files (_v5, _v6, …) so the user can compare and roll back.

Be honest about limits: the score is statistical, not guaranteed; you cannot promise an exact number; and you do not run the institutional tool — the user does.

---

8b. Knowledge baked into this skill

This skill is a consolidation of everything used to take the reference article from 50% to 13%. It does not depend on other skills being installed — the relevant knowledge is embedded here:

• Wikipedia "Signs of AI writing" (via the humanizer / humanizer-es / humanize-writing guides) — the full content/linguistic/style pattern catalogue, condensed in §5.8 and enforced by scan_leaks.py.
• Stylometric-detector findings from the real Compilatio Magister+ loop — the report-color parsing (§4), and the empirical result that colon-lists and symmetric enumerations are the highest-value fixes (§5.1–5.2, §7 targets).
• Burstiness metrics (text_metrics.py) and a heuristic leak scanner (scan_leaks.py) for blind mode.
• docx surgery (from the docx skill approach) — in-place XML edits that preserve styles instead of regenerating the document (§6).
• Optional detector-API self-check (§9) if a key is available.

If any of those standalone skills are installed, they compose fine, but none are required.

9. Optional: self-check with an AI detector API

If a detector API key is configured (e.g. HUMANIZERAI_API_KEY for the detect-ai skill), score the humanized text before the user submits, to catch obvious regressions. Absent a key, rely on §7 metrics + the user's report loop.

---

10. Quick start

Common setup:

pip install pymupdf pypdf defusedxml
unzip the .docx → note body paragraph indices (§3)

A) Report-driven (recommended when a report exists):

1. python3 scripts/analyze_report.py report.pdf         # blue (IA) + green (similarity)
2. map blue passages → paragraph indices; rewrite per §5 into edits.json
3. python3 scripts/replace_paragraphs.py unpacked/ edits.json ; zip → out.docx
4. python3 scripts/text_metrics.py unpacked/ <indices>  # confirm §7 targets
5. hand back out.docx (_vN); get next report; iterate §8 on remaining blue

B) Blind (no report):

1. python3 scripts/scan_leaks.py unpacked/ <indices>    # rank likely AI tells
2. rewrite the top offenders per §5 into edits.json
3. python3 scripts/replace_paragraphs.py unpacked/ edits.json ; zip → out.docx
4. python3 scripts/text_metrics.py unpacked/ <indices>  # confirm §7 targets
5. re-run scan_leaks; repeat until flagged share is low and metrics are human

Files in this skill:

SKILL.md
scripts/analyze_report.py       # report-driven: blue(IA)/green(similarity) from PDF
scripts/scan_leaks.py           # blind: heuristic AI-leak scanner (ES+EN)
scripts/replace_paragraphs.py   # rewrite paragraphs in .docx, keep formatting
scripts/text_metrics.py         # burstiness metrics

Deliver the file, a short changelog of which paragraphs changed and why, the metric deltas, and the honest note from §8.