What Are the Three Return Modes for Humanizer?

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.

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 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) 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.

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.

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 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 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 at lines 48-53, with additional implementation guidance available in 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 at lines 48-53 under the "What to return" metadata section. This file serves as the core skill definition for the blader/humanizer repository.

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