# How to Embed Humanizer in Commit Messages or Pull Request Descriptions: 6 Critical Constraints

> Discover the 6 critical constraints for embedding Humanizer in commit messages or PR descriptions. Learn to use embedded mode effectively, preserving code and avoiding new facts.

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

---

**When you embed Humanizer functionality within a commit message or pull request description, you must use embedded mode, which returns only the final rewritten text without intermediate artefacts, preserves all code blocks verbatim, and strictly prohibits inventing new facts.**

The open-source Humanizer repository (`blader/humanizer`) provides three distinct operation modes for refining AI-generated text. When integrating Humanizer into Git workflows to clean up commit messages or PR descriptions, the **embedded mode** defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) imposes specific architectural constraints to ensure the output remains suitable for version control systems and automated tooling.

## Why Embedded Mode Is Required for Git Workflows

Humanizer supports **pasted text**, **file mode**, and **embedded mode**. According to the source code in [[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)](https://github.com/blader/humanizer/blob/main/SKILL.md#L52), embedded mode is explicitly designed for scenarios where "another task uses this skill." In this mode, Humanizer returns a single cleaned string intended for direct insertion into automated workflows, unlike file mode which performs in-place editing or pasted text mode which shows intermediate steps.

## Six Constraints When Using Humanizer in Git Contexts

### 1. Final Text Output Only

In embedded mode, Humanizer **returns only the final rewritten text**. The output excludes all intermediate artefacts such as draft versions, lists of remaining "tells" (AI patterns), or critique commentary. This constraint ensures that commit messages and PR descriptions remain concise and free of auxiliary markup that could confuse Git parsers or human reviewers.

### 2. Strict Preservation of Code and Markup

Humanizer edits **only prose** and must preserve all technical content exactly as written. This includes:

- Code blocks and inline code
- Commands and file paths
- YAML metadata and data literals
- Link targets and URLs

Altering code or configuration inside a commit message would break reproducibility and introduce syntax errors, so the skill strictly prohibits such changes as documented in [[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)](https://github.com/blader/humanizer/blob/main/SKILL.md#L48).

### 3. Prohibition Against Fact Invention

The rewrite must **not add names, dates, quotes, or any factual detail** absent from the original text. Git history must accurately reflect the author's intent; fabricated facts would mislead reviewers and corrupt the permanent record. This constraint is enforced in the "What to return" section of [[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)](https://github.com/blader/humanizer/blob/main/SKILL.md#L46).

### 4. Plain-Text Output Requirements

The result is **plain text** without markdown headers, bold formatting, or other stylistic markup unless those elements were present in the source. Commit messages and PR bodies are frequently parsed as plain text by Git tooling, and unexpected markdown can interfere with log parsers or changelog generators.

### 5. Voice Matching for Authenticity

When a writing sample is supplied, Humanizer **matches the sample's rhythm, punctuation, and quirks** (including specific dash usage). This consistency preserves the author's voice in commit messages, ensuring the cleaned text feels authentic rather than generically processed. The voice matching logic is defined in [[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)](https://github.com/blader/humanizer/blob/main/SKILL.md#L42).

### 6. Task-Based Invocation Only

Embedded mode **requires invocation from a surrounding workflow** (such as a CI step or automation script). You cannot invoke Humanizer directly from the command line without wrapping it in a task. This architectural separation ensures the host workflow controls the integration, as specified in the embedded mode definition in [[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)](https://github.com/blader/humanizer/blob/main/SKILL.md#L52).

## Implementation Examples for CI/CD Pipelines

The following examples demonstrate how to implement these constraints in automated workflows.

### Example 1: Generating a Commit Message in a CI Script

```bash
#!/bin/bash

# Fetch AI-generated summary

AI_TEXT=$(curl -s https://example.com/ai-generated-summary.txt)

# Invoke Humanizer in embedded mode; only final text is returned

COMMIT_MSG=$(printf "%s\n" "$AI_TEXT" | /humanizer)

# Create commit with cleaned message

git add .
git commit -m "$COMMIT_MSG"

```

### Example 2: Embedding in a GitHub Actions PR Workflow

```yaml
steps:
  - name: Generate PR body
    id: gen-body
    run: |
      AI_BODY=$(cat docs/auto-generated-pr-body.md)
      # Humanizer returns only the final text, preserving all code blocks

      CLEAN_BODY=$(printf "%s\n" "$AI_BODY" | /humanizer)
      echo "body=$CLEAN_BODY" >> $GITHUB_OUTPUT

  - name: Create Pull Request
    uses: peter-evans/create-pull-request@v5
    with:
      title: "Add new feature"
      body: ${{ steps.gen-body.outputs.body }}

```

## Key Source Files and Configuration

Understanding these source files helps debug integration issues:

- **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)**: Defines the three operation modes and the exact wording of embedded mode constraints, including the "What to return" and voice matching specifications.
- **[`README.md`](https://github.com/blader/humanizer/blob/main/README.md)**: Provides installation instructions and general usage examples that illustrate how the skill is invoked across different contexts.
- **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)**: Contains the default prompt that agents use when loading the Humanizer skill, showing how the system presents constraints to different AI agents.

## Summary

- Use **embedded mode** exclusively when you embed Humanizer functionality within a commit message or pull request description.
- Expect **only final text** without drafts, pattern lists, or commentary.
- **Preserve all code blocks, paths, and markup** exactly as provided.
- **Never invent facts** such as dates, names, or quotes not present in the source.
- Output **plain text** without additional markdown formatting unless pre-existing.
- **Invoke from a surrounding task** rather than using direct CLI execution.

## Frequently Asked Questions

### Can I invoke Humanizer directly from the command line for commit messages?

No. Embedded mode requires invocation from a surrounding workflow or task. Direct CLI usage without task wrapping violates the architectural design specified in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). You must wrap the call inside a CI step, Git hook, or automation script.

### Will Humanizer reformat or improve code examples in my PR description?

No. The skill strictly edits prose and preserves code blocks, inline code, commands, paths, YAML metadata, and link targets exactly as written. It will not alter syntax, indentation, or technical content, ensuring reproducibility and preventing syntax errors.

### Can I ask Humanizer to add markdown headers or bold text for emphasis?

No, unless those formatting elements already exist in the source text. Embedded mode returns plain text output by default. Adding markdown headers or bold formatting could interfere with Git tooling that parses commit logs as plain text.

### What happens if I don't provide a writing sample?

Without a writing sample, Humanizer will clean the text using standard conventions but cannot match a specific voice or rhythm. For best results in commit messages—where author consistency matters—provide a sample in the environment variable or input stream as documented in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md).