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

> Master Humanizer's file mode to rewrite prose in place while preserving code and frontmatter. Get a detailed summary of changes for efficient document processing.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: how-to-guide
- Published: 2026-09-07

---

**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](https://github.com/blader/humanizer) repository.

## What Is Humanizer File Mode?

The **file mode** is defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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

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

```

**Result**: [`docs/launch-post.md`](https://github.com/blader/humanizer/blob/main/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)

```markdown
/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`](https://github.com/blader/humanizer/blob/main/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/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) | Complete file-mode specification and 25 rewrite patterns【https://github.com/blader/humanizer/blob/main/SKILL.md#L48-L53】 |
| [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) | User-facing invocation examples【https://github.com/blader/humanizer/blob/main/README.md#L44-L48】 |
| [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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)【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`](https://github.com/blader/humanizer/blob/main/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】.