Functional Differences Between Humanizer's Three Output Modes: Pasted‑Text, File, and Embedded

Humanizer provides three distinct output modes—Pasted‑Text (default), File, and Embedded—that control whether the skill returns intermediate drafts and diagnostic data, writes directly to disk, or acts as a silent text filter for parent skills.

Humanizer is a Markdown‑based skill that rewrites AI‑generated prose into natural human language. According to the blader/humanizer source code, each mode influences the workflow, the amount of information returned, and how the result is applied to the surrounding context.

Pasted‑Text Mode (Default)

Pasted‑text mode is triggered when you paste raw text directly into the skill without supplying a file path. This mode is optimized for interactive editing and learning how the rewrite logic works.

In this mode, Humanizer returns three distinct pieces of information:

• The draft rewrite (first pass)
• A short list of any remaining AI‑style patterns detected after the draft
• The final rewritten text

This transparency allows you to see which patterns were still present after the first pass and exactly how the final text differs from the draft. It is the default behavior defined in SKILL.md for manual, interactive use cases.

File Mode

File mode activates when you supply a file path (e.g., Humanize the prose in docs/launch‑post.md). Instead of displaying the full rewrite pipeline, Humanizer writes only the final result back to the specified file and presents a brief summary to the user.

Key characteristics of File mode:

• Output destination: Only the final rewritten prose is written back to the file path provided
• User feedback: The caller receives a short summary (e.g., "✅ 12 sentences updated, 3 patterns removed")
• Content preservation: Humanizer respects code blocks, front‑matter, YAML metadata, inline code, commands, paths, and link targets, leaving them untouched while rewriting only the prose

This mode is ideal for batch processing documentation or cleaning up existing Markdown files in place.

Embedded Mode

Embedded mode functions as a pure text filter with no UI noise. It is invoked when another task calls Humanizer as a sub‑skill—for example, during pull‑request reviews, commit‑message generation, or document‑generation pipelines.

In this mode, the skill returns only the final rewritten text, omitting the draft, the pattern list, and any summary. The parent skill receives the cleaned text directly, enabling seamless composition without extraneous diagnostic information cluttering the output.

Implementation Details

The mode definitions reside entirely in SKILL.md (see the What to return section at lines 46‑53). Because Humanizer is implemented as a plain‑Markdown skill, there is no separate codebase; the mode handling is performed by the agent runtime that parses these headings and returns the appropriate payload.

The architectural flow is consistent across all three modes:

1. Input detection: The runtime checks whether the user supplied a file path (File mode), invoked the skill from another skill (Embedded mode), or simply pasted text (Pasted‑text).
2. Processing pipeline: Humanizer always executes the same three‑step pipeline: mark tells → draft rewrite → final rewrite.
3. Mode‑specific output: The runtime formats the response according to the detected mode, either returning diagnostic data, writing to disk, or passing clean text upward.

Additional configuration files supporting these modes include README.md (user documentation for invocation) and agents/openai.yaml (display name and default prompt for OpenAI‑compatible agents).

Code Examples

Pasted‑Text Invocation

/humanizer
[Paste AI‑generated paragraph here]

Returns:

• Draft rewrite
• Remaining pattern list
• Final rewrite

File Mode Invocation

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

Behavior: Updates docs/launch-post.md in‑place (only the prose content), while the user sees a short summary like: "✅ 12 sentences updated, 3 patterns removed."

Embedded Mode Invocation

/humanizer:humanizer
<text from a pull‑request description>

Returns: Only the cleaned text back to the parent skill, ready for insertion into the PR body.

Summary

• Pasted‑text mode provides full transparency with draft, pattern list, and final output for interactive learning.
• File mode writes only the final result to disk, preserves non‑prose elements (code blocks, YAML front matter), and shows a concise summary.
• Embedded mode returns only the final text, acting as a silent filter for compositional workflows.
• All three modes share the same core processing pipeline; only the output formatting differs based on the runtime's parsing of SKILL.md.

Frequently Asked Questions

When should I use File mode instead of Pasted‑text mode?

Use File mode when you need to process an existing document in place and want to preserve technical elements like code fences, inline commands, and YAML front matter. Use Pasted‑text mode when you are interactively editing a block of text and want to see Humanizer's intermediate drafts to understand how it transforms AI‑style patterns.

Can I see the intermediate draft when using Embedded mode?

No. Embedded mode intentionally returns only the final rewritten text with no draft, pattern list, or summary. This design ensures that parent skills receive clean output without diagnostic noise. If you need visibility into the transformation process, invoke Humanizer in Pasted‑text mode instead.

How does Humanizer protect code blocks and metadata in File mode?

According to the skill specification in SKILL.md, File mode is designed to respect code blocks, front‑matter, YAML metadata, inline code, commands, paths, and link targets. The rewrite logic specifically targets prose sections while leaving these structural elements untouched, ensuring that technical documentation remains functional after humanization.

Where are the three output modes defined in the repository?

The functional definitions for all three modes are located in SKILL.md at lines 46‑53 within the What to return section. The runtime uses this specification to determine which payload structure to return based on input detection (file path, sub‑skill invocation, or pasted text). Supporting documentation can be found in README.md and agent configuration in agents/openai.yaml.

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