# What Are the Three Return Modes for Humanizer?

> Explore the three return modes of Humanizer: pasted text, file mode, and embedded mode. Choose the best option for your integration needs, from simple rewrites to automated pipelines.

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

---

**Humanizer supports three return modes: pasted text (default), file mode, and embedded mode, each designed for different integration scenarios from simple rewrites to automated pipeline consumption.**

The **blader/humanizer** repository provides an AI text humanization skill with flexible output formats. Understanding these three return modes is essential for integrating Humanizer effectively into your workflow, whether you're manually editing prose or embedding it in automated systems.

## Pasted Text Mode (Default)

The **pasted text mode** is Humanizer's default behavior when you supply a plain text block directly.

In this mode, Humanizer returns three components:

1. The draft with tracked edits
2. A concise list of any remaining AI-style patterns detected
3. The final cleaned paragraph ready for use

This mode is ideal for quick, interactive rewrites where you want visibility into what changed and what patterns might still need attention.

```text
User: Rewrite the following paragraph.

> It's not just about speed; it's about reliability. That is the real win.

Humanizer returns:
- Draft with edits
- List of remaining patterns
- Final cleaned paragraph

```

The return structure is defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under the **"What to return"** metadata section at lines 48-53.

## File Mode

The **file mode** activates when you provide a file path (e.g., [`mydoc.md`](https://github.com/blader/humanizer/blob/main/mydoc.md)) instead of raw text. Humanizer rewrites the entire file while preserving structural elements that should not be altered.

Specifically, file mode leaves untouched:

- Code blocks
- Inline code
- Commands
- File paths
- YAML metadata
- Data
- Link targets

After processing, Humanizer writes only the final text back to the original file and provides a short verbal summary.

```text
User: Humanizer file: notes.txt

Humanizer rewrites `notes.txt` in place, leaving code blocks, YAML front‑matter, etc. untouched, then replies:
> Updated `notes.txt`. Summary: removed redundant closers and not‑X‑but‑Y contrasts.

```

This mode is suited for batch processing documents where you need in-place updates with protection for technical syntax.

## Embedded Mode

The **embedded mode** is designed for programmatic integration. When Humanizer is called from another task—such as a pull-request reviewer, commit-message generator, or document-assembler—it returns **only** the final rewritten text without extra metadata.

```text
User: (inside a PR review) Apply Humanizer to the description.

Humanizer returns only:
> The updated description without AI‑style patterns.

```

This stripped output prevents pipeline contamination and keeps downstream processing simple. No draft, no pattern list, no summaries—just clean prose.

## How to Specify Return Modes

According to the [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) specification in **blader/humanizer**, the return mode is determined by input context:

| Input Pattern | Return Mode Activated |
|-------------|----------------------|
| Plain text block | Pasted text (default) |
| `file: <path>` or filename reference | File mode |
| Called from another skill/agent without explicit format request | Embedded mode |

The skill metadata in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) explicitly defines these three options under **"What to return"**, making the behavior predictable across different agent platforms.

## Summary

- **Pasted text mode** — Returns draft, pattern list, and final text for interactive use
- **File mode** — Rewrites files in place, preserves technical syntax, provides brief summary
- **Embedded mode** — Returns only clean text for programmatic consumption in automated pipelines

All three return modes are documented in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) at lines 48-53, with additional implementation guidance available in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) for cross-platform portability.

## Frequently Asked Questions

### What is the default return mode for Humanizer?

**Pasted text mode is the default.** When you provide raw text without file references or embedding context, Humanizer returns the full suite: draft with edits, remaining pattern list, and final cleaned paragraph.

### Does file mode preserve YAML front matter?

**Yes.** File mode specifically protects YAML metadata, code blocks, inline code, commands, paths, data, and link targets from modification. Only the prose content is rewritten.

### When should I use embedded mode?

**Use embedded mode when integrating Humanizer into automated workflows** such as CI/CD pipelines, PR review bots, or document assemblers. The single-value return prevents parsing complexity downstream.

### Where are the return modes defined in the source?

**The return modes are specified in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** at lines 48-53 under the **"What to return"** metadata section. This file serves as the core skill definition for the blader/humanizer repository.