How Humanizer's File Mode Works: A Complete Guide to In-Place Rewriting

Humanizer's file mode processes an entire document in one command, rewriting only the prose while preserving all code blocks, inline code, YAML frontmatter, and link targets, then returns a concise summary of changes.

Humanizer supports two input modes: pasted text (default) and file mode, where you supply a file path instead of raw content. This guide explains the complete file-mode pipeline, from path detection to selective write-back, based on the implementation in the blader/humanizer repository.

What Is Humanizer File Mode?

The file mode is defined in SKILL.md as:

"When the user names a file, run the full process but write only the final text to the file. Change prose only. Keep code blocks, inline code, commands, paths, YAML metadata, data, and link targets unchanged. Then give the user a short summary."【https://github.com/blader/humanizer/blob/main/SKILL.md#L50-L53】

This means you can humanize an entire Markdown, Python, or documentation file without touching its functional elements.

The File Mode Pipeline in 5 Steps

1. Input Detection

Humanizer checks whether user input matches a file path pattern. Triggers include:

• Extensions like .md, .py, .js, .tsx
• Directory prefixes like docs/, src/, blog/

2. File Loading and Content Splitting

The file is read from disk and parsed into two categories:

Section Type	Examples	Handling
Prose	Paragraphs, headings, list text	Rewritten
Non-prose	Code fences, inline `code`, YAML frontmatter, file paths, URLs, data structures	Preserved exactly

3. Tell Detection and Rewriting

Prose sections flow through Humanizer's standard pipeline:

• Mark tells – Identify weasel words, weak hedges, corporate jargon, and 25+ anti-patterns
• Draft rewrite – Generate improved version
• Check draft – Validate against the 25 rewrite patterns
• Final rewrite – Produce polished prose

This logic is identical to pasted-text mode; only the input source differs.

4. Selective Write-Back

The critical step: only edited prose sections replace their originals. Everything else is spliced back unchanged. The modified file is saved to disk in place.

5. User Feedback

Humanizer emits a concise summary of what changed:

✅ Updated 4 paragraphs
🔹 Removed 2 "not-X-but-Y" contrasts
🔹 Replaced 3 em dashes with commas

Humanizer File Mode Examples

Basic File Mode Invocation

/humanizer
Humanize the prose in docs/launch-post.md

Result: docs/launch-post.md is rewritten in place. Console shows the change summary【https://github.com/blader/humanizer/blob/main/README.md#L44-L48】.

Preview Mode (No File Modification)

/humanizer
Humanize the prose in src/utils/helpers.py

When embedded in another skill or called with specific flags, Humanizer returns only the cleaned-up prose without writing to disk. Useful for PR generation or review workflows.

Why File Mode Uses No External Code

The entire file-mode behavior is driven by the markdown skill. The same SKILL.md file powers both normal and file modes:

• Portable – Works across any agent that can load SKILL.md【https://github.com/blader/humanizer/blob/main/AGENTS.md】
• Consistent – Identical rewrite quality regardless of input method
• Maintainable – Single source of truth for all logic

Key Files for Understanding File Mode

File	Purpose
SKILL.md	Complete file-mode specification and 25 rewrite patterns【https://github.com/blader/humanizer/blob/main/SKILL.md#L48-L53】
README.md	User-facing invocation examples【https://github.com/blader/humanizer/blob/main/README.md#L44-L48】
AGENTS.md	Confirms cross-agent portability【https://github.com/blader/humanizer/blob/main/AGENTS.md】

Summary

• File mode accepts a file path instead of pasted text
• Only prose is rewritten; code, YAML, paths, and links remain untouched
• Five-step pipeline: detect path → load and split → process prose → splice and save → return summary
• Zero external dependencies – behavior defined entirely in SKILL.md
• Cross-agent compatible via skill-based architecture

Frequently Asked Questions

How do I invoke Humanizer file mode?

Pass a file path as your input. Humanizer automatically detects file mode when the input matches path patterns (extensions like .md or prefixes like docs/). The file is rewritten in place with only prose sections modified.

Does file mode preserve code blocks and YAML frontmatter?

Yes. File mode explicitly preserves code blocks, inline code, command snippets, file-system paths, YAML frontmatter, data structures, and link targets. Only human-readable paragraphs are rewritten according to SKILL.md【https://github.com/blader/humanizer/blob/main/SKILL.md#L50-L53】.

Can I preview changes without modifying the file?

Yes. When Humanizer is called from another skill or with specific context, it returns the cleaned prose without writing to disk. This is useful for generating pull request descriptions or review comments.

Why does file mode work across different AI agents?

The entire behavior is defined in SKILL.md, a markdown-based skill specification. Any agent that can load and execute skill files can run Humanizer's file mode without custom code changes【https://github.com/blader/humanizer/blob/main/AGENTS.md】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}