# What Is the Purpose of AGENTS.md in the Humanizer Project?

> Discover the role of AGENTS.md in the Humanizer project. This guide details how to edit and maintain skills, ensuring version consistency and cross-agent compatibility for contributors.

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

---

**AGENTS.md serves as the authoritative developer guide and single source of truth for contributors to the blader/humanizer repository, documenting exactly how to edit and maintain the pure-Markdown skill while enforcing version consistency and cross-agent compatibility.**

The [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) file in the **blader/humanizer** repository functions as the primary governance document for anyone modifying the codebase. Unlike typical contributing guides that focus on coding standards, this file addresses the unique constraints of maintaining a **pure-Markdown skill** that contains no build step and relies entirely on synchronized text files. It establishes the structural rules necessary to keep the package stable and portable across different AI agent implementations.

## Repository Scope and Core Architecture

According to [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), Humanizer is explicitly defined as a **pure-Markdown skill** with zero build dependencies. The only executable prompt resides in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), making the repository fundamentally different from traditional software projects that compile or bundle code.

The document inventories the **core assets** that collectively form the skill:

- [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) – Contains the single source of truth for the skill's executable prompt and YAML metadata
- [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) – Hosts the user-facing documentation, pattern reference table, and version changelog
- [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) – The Claude plugin descriptor that points to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
- [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) – The automated validator ensuring cross-file consistency

## Change Control and Maintenance Rules

[`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) mandates strict **change-control rules** to prevent the repository from drifting into an inconsistent state. These rules govern every aspect of modification, from adding new functionality to updating version strings.

### Pattern Integrity Across 35 Numbered Rules

The skill implements exactly **35 numbered patterns** for text transformation. When contributors add, remove, or renumber any pattern, [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) requires synchronized updates across every reference:

- The pattern table in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) must reflect the new numbering
- The Python validator in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) must account for the changes
- Any hardcoded references in documentation must be adjusted

This prevents scenarios where the skill prompt expects pattern 36 while the README only documents 35 entries.

### Version Synchronization Requirements

Every release requires updating the **version string** in three distinct locations simultaneously:

1. The YAML metadata block at the top of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
2. The first entry of the changelog in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)
3. The `version` field in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)

The following commands verify version alignment before publishing:

```bash

# Check SKILL.md metadata version

jq '.metadata.version' SKILL.md

# Check Claude plugin manifest version

jq '.version' .claude-plugin/plugin.json

```

### Cross-Agent Compatibility Standards

To maintain portability, [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) prohibits agent-specific language in installation or usage instructions. Documentation must remain **implementation-neutral**, ensuring the skill loads correctly in Claude, GPT, or any other compatible agent without requiring forked documentation.

### Historical Tracking Requirements

Any non-obvious modification or behavior change must be recorded in the **README's version notes**. This creates an audit trail explaining why specific patterns behave differently across versions, which is critical for debugging downstream issues.

## Validation Workflow and Quality Gates

Before any contribution can be published, [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) mandates running three distinct validation layers to guarantee package consistency.

The **automated validation suite** includes:

```bash

# Run the repository-wide Python validator

python3 scripts/validate-package.py

# Execute the skills inspector via npx

npx skills inspector

# Validate the Claude plugin manifest

# (Claude plugin validator command as specified in AGENTS.md)

```

These checks verify that pattern counts match between files, version strings align, and the YAML frontmatter in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) parses correctly.

## Writing Style Guidelines

Beyond technical constraints, [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) prescribes a **plain-language writing style** for all comments, prompts, and documentation. This ensures readability across different agent contexts and prevents ambiguity in the skill's instructions.

When adding new patterns to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), contributors follow this structure:

```yaml
- role: user
  content: |
    # 36. Convert numbers to Roman numerals

    {{input}} → {{romanize input}}

```

And synchronize the README table immediately:

```bash
sed -i '42a| 36 | Convert numbers to Roman numerals | {{input}} → {{romanize input}} |' README.md

```

## Summary

- **AGENTS.md** acts as the authoritative constitution for the blader/humanizer repository, governing how the pure-Markdown skill evolves.
- The file mandates **strict synchronization** across [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) whenever patterns or versions change.
- **Thirty-five numbered patterns** form the core functionality, and modifying them requires updating every reference in validators and documentation.
- **Triple validation** via [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), `npx skills`, and the Claude plugin validator prevents broken releases.
- **Cross-agent neutrality** ensures the skill remains portable and implementation-agnostic.

## Frequently Asked Questions

### What is AGENTS.md in the Humanizer project?

**AGENTS.md is the authoritative developer guide** that documents how to edit and maintain the Humanizer skill. It serves as the single source of truth for contributors, establishing rules for version control, file synchronization, and stylistic standards to ensure the repository remains stable and compatible with any AI agent that loads the skill.

### How does AGENTS.md enforce version consistency?

The file requires that the version string appear identically in three locations: the YAML metadata of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), the first entry of the [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) changelog, and the manifest in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json). Contributors must verify alignment using `jq` commands before publishing, ensuring that agents load the correct skill version.

### What validation steps are required before publishing changes?

Contributors must run the **Python validation script** (`python3 scripts/validate-package.py`), the **skills inspector** (`npx skills inspector`), and the **Claude plugin validator** to check for pattern count mismatches, YAML syntax errors, and version string discrepancies. These three layers prevent inconsistent states from reaching production.

### Why must pattern changes update multiple files?

Humanizer contains **35 numbered patterns** that are referenced in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), tabulated in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and enumerated in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py). If a contributor adds pattern 36 to the skill prompt but fails to update the README table or validator, the package enters an inconsistent state where documentation and validation logic disagree with the actual skill behavior, breaking cross-agent compatibility.