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

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 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, Humanizer is explicitly defined as a pure-Markdown skill with zero build dependencies. The only executable prompt resides in 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 – Contains the single source of truth for the skill's executable prompt and YAML metadata
• README.md – Hosts the user-facing documentation, pattern reference table, and version changelog
• .claude-plugin/plugin.json – The Claude plugin descriptor that points to SKILL.md
• scripts/validate-package.py – The automated validator ensuring cross-file consistency

Change Control and Maintenance Rules

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 requires synchronized updates across every reference:

• The pattern table in README.md must reflect the new numbering
• The Python validator in 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
2. The first entry of the changelog in README.md
3. The version field in .claude-plugin/plugin.json

The following commands verify version alignment before publishing:

# 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 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 mandates running three distinct validation layers to guarantee package consistency.

The automated validation suite includes:

# 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 parses correctly.

Writing Style Guidelines

Beyond technical constraints, 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, contributors follow this structure:

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

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

And synchronize the README table immediately:

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, README.md, and .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, 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, the first entry of the README.md changelog, and the manifest in .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, tabulated in README.md, and enumerated in 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.

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