# Contributor Rules for Humanizer's SKILL.md and README.md: AGENTS.md Guidelines Explained

> Master blader/humanizer contributor rules for SKILL.md and README.md. Learn synchronization, numbering, and validation scripts to ensure seamless updates and avoid errors.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: best-practices
- Published: 2026-09-11

---

**Contributors to blader/humanizer must keep [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) perfectly synchronized by maintaining sequential pattern numbering without gaps, aligning all cross-references and version fields across three files, and validating changes with [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) before publishing.**

The `blader/humanizer` repository defines an AI skill for humanizing text output through pattern-based instructions. To maintain consistency across the skill definition and user documentation, the project enforces strict contributor rules documented in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md). These rules ensure that the core logic in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) remains aligned with the presentation in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) while supporting multiple agent platforms.

## Pattern Numbering and Organization Rules

Patterns in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) must follow a strict sequential structure starting at **1 with no gaps** allowed. The strongest and most frequent patterns appear first in descending order of importance.

When adding new patterns, contributors must verify the pattern does not duplicate existing coverage. If similar logic exists, the new content should fold into the appropriate existing pattern rather than creating a separate entry. This sequential requirement applies strictly to the headings in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), as the validation script derives the pattern count directly from these headings.

## README-SKILL.md Synchronization Requirements

Any modification to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) requires immediate corresponding updates to [`README.md`](https://github.com/blader/humanizer/blob/main/README.md). According to the rules in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), the following elements must remain synchronized:

- **README tables** displaying pattern overviews
- **README section titles** matching pattern descriptions
- **Every `§` reference** pointing to specific patterns

The validator checks for mismatches between these files, and any discrepancy causes the validation script to fail. When renumbering patterns—such as deleting pattern 15 and shifting subsequent numbers down—contributors must update all `§` references throughout the documentation to reflect the new numbering.

## Version Consistency Across Files

The repository maintains a three-way version lock between [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and the plugin descriptor. The `metadata.version` field inside [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) must match exactly:

1. The first version entry in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)
2. The version field in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)

Contributors must never add a top-level `version` field directly to the skill definition. When updating versions, change all three locations simultaneously:

```yaml

# In SKILL.md

metadata:
  version: 3.1.0

```

```json
// In .claude-plugin/plugin.json
{
  "version": "3.1.0"
}

```

Additionally, the [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) version history table must include a new entry at the top for every behavior-changing or non-obvious fix.

## Platform-Agnostic Documentation Standards

Installation and usage instructions must remain **agent-agnostic** across all documentation. The rules prohibit mentioning specific platforms like Claude or OpenAI in the core instructions, though platforms may appear as examples. This neutrality ensures the skill works across different AI agent implementations without appearing biased toward any particular ecosystem.

The [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) file maintains its own display name and default prompt synchronization, but the main README and SKILL documentation avoid platform-specific terminology in the primary workflow descriptions.

## Pre-Publish Validation Workflow

Before submitting or publishing changes, contributors must execute the validation suite to enforce all synchronization rules. Run these commands in sequence:

```bash

# Validate package integrity and cross-file consistency

python scripts/validate-package.py

# List skills to verify registration

npx skills add . --list

# Validate Claude plugin specifically

claude plugin validate .

```

These scripts catch mismatches between pattern counts, version numbers, and cross-references early in the development process. The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script specifically checks that [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) headings align with [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) tables and that all `§` references resolve correctly.

## Summary

- **Sequential numbering**: Patterns start at 1 with no gaps, ordered by strength.
- **File synchronization**: Update README tables, titles, and `§` references whenever [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) changes.
- **Version locking**: Keep `metadata.version` in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) identical to the first entry in [`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).
- **Platform neutrality**: Write installation instructions without referencing specific AI platforms.
- **Validation requirement**: Run [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) and platform-specific validators before every publish.

## Frequently Asked Questions

### What happens if I add a pattern number that creates a gap in the sequence?

The validation script will fail. According to [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), patterns must be numbered sequentially without gaps, and the validator derives the expected count directly from [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) headings. Any gap triggers a mismatch error during the pre-publish validation phase.

### How do I update the version when making a change?

Update the `metadata.version` field in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), change the first version entry in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) to match, and set the same version in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json). Do not add a top-level `version` field to the skill itself. Finally, add a short entry to the README version history describing the change.

### Can I mention Claude-specific features in the installation instructions?

No. The contributor rules require installation and usage sections to remain agent-agnostic. While you may use platforms as examples, the core instructions must not favor or require specific platforms like Claude or OpenAI, ensuring compatibility across different agent ecosystems.

### What files must I check when deleting a pattern?

When removing a pattern, delete the section from [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), shift all subsequent pattern numbers down to close the gap, update the pattern table in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and fix every `§` reference throughout the documentation. Run [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) to verify no broken references remain.