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

Contributors to blader/humanizer must keep SKILL.md and 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 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. These rules ensure that the core logic in SKILL.md remains aligned with the presentation in README.md while supporting multiple agent platforms.

Pattern Numbering and Organization Rules

Patterns in 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, as the validation script derives the pattern count directly from these headings.

README-SKILL.md Synchronization Requirements

Any modification to SKILL.md requires immediate corresponding updates to README.md. According to the rules in 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, README.md, and the plugin descriptor. The metadata.version field inside SKILL.md must match exactly:

1. The first version entry in README.md
2. The version field in .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:

# In SKILL.md

metadata:
  version: 3.1.0

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

Additionally, the 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 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:

# 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 script specifically checks that SKILL.md headings align with 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 changes.
• Version locking: Keep metadata.version in SKILL.md identical to the first entry in README.md and .claude-plugin/plugin.json.
• Platform neutrality: Write installation instructions without referencing specific AI platforms.
• Validation requirement: Run 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, patterns must be numbered sequentially without gaps, and the validator derives the expected count directly from 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, change the first version entry in README.md to match, and set the same version in .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, shift all subsequent pattern numbers down to close the gap, update the pattern table in README.md, and fix every § reference throughout the documentation. Run scripts/validate-package.py to verify no broken references remain.

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