How Humanizer Handles Input Types and Output Modes

Humanizer detects whether you provide plain text, a file path, or a writing sample, then returns results in one of three adaptive output modes: pasted-text (default), file, or embedded.

The blader/humanizer repository is a pure-Markdown skill that transforms AI-generated prose into natural human writing. Understanding how Humanizer handles different input types and output modes is critical for deploying it effectively in chat interfaces, automated file processing, or embedded pipeline workflows.

Input Type Detection

According to SKILL.md (lines 28-30), Humanizer first inspects the payload to determine which of three input types it received. This detection triggers specific processing logic downstream.

Plain Text Input

When a user invokes the /humanizer command and pastes raw text directly into the chat interface, Humanizer treats this as plain text input. This is the default interaction pattern for ad-hoc rewriting tasks where no file persistence is required.

File Path Input

If the input string contains a file reference (e.g., Humanize the prose in docs/launch-post.md), Humanizer enters file mode. The skill reads the target file’s contents, processes only the narrative prose sections, and preserves structural elements like code blocks, YAML frontmatter, and link targets during the rewrite.

Writing Sample Input

Users may optionally provide a writing sample that instructs Humanizer on the author’s specific voice and style preferences. This input type modifies the rewrite process but does not change the output mode selection logic.

Output Modes

As defined in SKILL.md (lines 32-39), Humanizer selects from three distinct output modes based on the input context and calling environment. Each mode controls exactly what data returns to the user or calling process.

Pasted-Text Mode (Default)

In default mode, triggered by plain text input without file references, Humanizer returns a complete diagnostic package:

• The initial draft with highlighted AI patterns
• A list of remaining patterns (if any persist after rewriting)
• The final rewritten text ready for use

This mode prioritizes transparency and educational feedback for interactive chat sessions.

File Mode

When processing a file path, Humanizer executes file mode. Rather than returning the full text to the chat window, the skill writes only the final rewritten prose back to the original file, leaving all non-prose sections untouched. It then returns a concise summary to the user (e.g., "✅ Updated 3 paragraphs, 2 patterns removed").

Embedded Mode

Embedded mode activates when another skill or automated task invokes Humanizer programmatically (e.g., from a pull-request generator or commit-message tool). In this mode, Humanizer returns only the final cleaned text without the draft, pattern list, or explanatory metadata, allowing seamless insertion into templates or downstream processing.

Internal Processing Pipeline

Regardless of input type, Humanizer follows a deterministic three-stage pipeline implemented in the core skill logic:

1. Parse Input – Detect whether the payload contains raw text, a file reference, or a writing-sample block
2. Execute Rewrite – Run the standard three-pass transformation (pattern detection → draft generation → final polish)
3. Apply Mode-Specific Handling – Format the return value according to the selected output mode:
   • File mode: Persist changes to disk, return summary only
   • Embedded mode: Strip metadata, return text only
   • Default mode: Return full diagnostic bundle

This architecture ensures consistent text processing while allowing flexible integration patterns across different tooling ecosystems.

Practical Implementation Examples

Example 1: Interactive Pasted Text

/humanizer

Please humanize this text:
[paste AI-generated paragraph here]

Humanizer returns the draft, pattern analysis, and final rewrite in the chat thread.

Example 2: File-Based Processing

Humanize the prose in docs/launch-post.md

Humanizer updates docs/launch-post.md in-place, preserving all code blocks and frontmatter, then prints a completion summary.

Example 3: Embedded API Usage

{
  "skill": "humanizer",
  "input": {
    "text": "…AI-generated text…",
    "mode": "embedded"
  }
}

The calling application receives only the cleaned text string, ready for embedding into a PR description or automated report.

Summary

• Input Types: Humanizer distinguishes between plain text (chat), file paths (batch processing), and writing samples (voice tuning) to determine processing context
• Output Modes: Three return formats exist—pasted-text (full diagnostics), file (in-place rewrite with summary), and embedded (text-only for APIs)
• Source Definition: All input and output logic is centralized in SKILL.md at lines 28-30 and 32-39
• Validation: The repository includes scripts/validate-package.py to ensure skill metadata remains synchronized when extending these input/output handlers

Frequently Asked Questions

What happens if Humanizer detects both text and a file path in the input?

Humanizer prioritizes the file path and enters file mode, processing the specified file while ignoring the pasted text. According to the logic in SKILL.md, the presence of a valid file path triggers the file-specific handler that reads from disk rather than the chat buffer.

Does file mode preserve YAML frontmatter and code blocks?

Yes. When operating in file mode, Humanizer specifically preserves code blocks, YAML frontmatter, data tables, and link targets. The skill only rewrites narrative prose sections, ensuring that technical documentation structure remains intact while the writing voice is humanized.

How does embedded mode differ from the default pasted-text mode?

Embedded mode returns only the final rewritten text string, making it suitable for API integrations and automation pipelines. In contrast, pasted-text mode (the default) returns a verbose response including the draft with highlighted patterns and a list of remaining issues, designed for educational review in chat interfaces.

Can I force a specific output mode when using the /humanizer command?

The output mode is automatically determined by input type detection rather than explicit flags. Plain text triggers pasted-text mode, file paths trigger file mode, and programmatic calls from other skills trigger embedded mode. The repository's validation script (scripts/validate-package.py) ensures these mode transitions remain consistent across skill updates.

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