How the Validator Script Maintains Consistent Pattern Numbering Across SKILL.md and README.md

The scripts/validate-package.py script enforces documentation synchronization by extracting pattern numbers from both files using targeted regex, validating contiguous sequences starting at 1, and performing bidirectional list comparison to ensure exact one-to-one correspondence.

The blader/humanizer repository relies on precise pattern numbering to maintain integrity between its canonical definitions and public documentation. The validator script implements a deterministic six-step pipeline that prevents documentation drift by verifying every pattern identifier in SKILL.md appears exactly once in README.md without gaps, duplicates, or misordering.

Loading Source Files and Extraction Strategy

The validation process begins by ingesting both documentation files and applying file-specific regular expressions to isolate pattern identifiers.

Ingesting SKILL.md and README.md

In scripts/validate-package.py, lines 21-23 load the entire contents of SKILL.md and README.md into the variables SKILL and README. This initial step ensures the validator operates on complete file contents before executing pattern extraction.

Parsing SKILL.md Headings

Lines 66-69 scan the loaded SKILL content for hierarchical headings that define individual patterns. The script searches for lines matching the regex pattern ^### (\d+)\. , extracting every integer into a list called pattern_numbers.

# Conceptual representation of lines 66-69

pattern_numbers = [int(match) for match in re.findall(r'^### (\d+)\. ', skill_content)]

This extraction captures the canonical pattern sequence as defined in the source documentation, creating the authoritative reference list for subsequent validation steps.

Scraping README.md Tables

Lines 74-76 perform a complementary extraction on the README content, targeting table rows that list patterns using the format | <number> |. The script converts these matches to integers and stores them in readme_numbers.

# Conceptual representation of lines 74-76

readme_numbers = [int(match) for match in re.findall(r'\| (\d+) \|', readme_content)]

Validating Sequence Integrity and Cross-Referencing

Once extracted, both lists undergo rigorous validation to ensure structural correctness and mutual consistency before the script declares the package valid.

Enforcing Contiguous Ranges

Lines 71-73 verify that pattern_numbers forms a non-empty, contiguous sequence starting exactly at 1. The script validates that the list equals [1, 2, …, n] without gaps or out-of-order elements.

If the validation detects missing numbers—such as [1, 2, 4] instead of [1, 2, 3, 4]—the script aborts immediately with the error:

SystemExit: Number SKILL.md patterns from 1 upward without gaps: [1, 2, 4]

Bidirectional List Comparison

Lines 77-80 perform the critical synchronization check. The script sorts readme_numbers and verifies it exactly matches pattern_numbers in both content and length. Any discrepancy—whether missing patterns, extra entries, or duplicates—triggers a descriptive error message:

SystemExit: List patterns 1 through 5 once each in the README tables: [1, 2, 3, 4, 5]

This bidirectional comparison ensures that README.md contains precisely the same pattern set as SKILL.md, maintaining strict one-to-one correspondence between source definitions and public tables.

Synchronizing the Summary Header

Line 81 adds a final consistency layer by verifying that README.md contains a section header reflecting the total pattern count: ## The <n> patterns. This ensures the human-readable summary stays synchronized with the actual extracted pattern list derived from SKILL.md.

Running the Validator Locally

Developers can execute the validation pipeline manually to verify documentation integrity before submitting changes to the repository.

Execution Command

Run the validator from the repository root using Python 3:

python3 scripts/validate-package.py

Success and Failure Outputs

Successful validation produces a concise confirmation indicating version alignment:

Humanizer package v3.0.0 is valid

Failure scenarios provide specific remediation guidance that identifies the exact nature of the mismatch:

• Missing pattern in README.md: Lists the expected pattern range versus the actual found set
• Gap in SKILL.md numbering: Displays the non-contiguous sequence violating the [1, n] requirement
• Version mismatch: Compares versions between .claude-plugin/plugin.json and markdown file headers

Key Files in the Validation Ecosystem

The validator operates across four critical files that collectively maintain package integrity according to the source code analysis:

• SKILL.md – Primary source containing pattern definitions using ### <number>. headings

• README.md – Public documentation with pattern tables using | <number> | rows

• scripts/validate-package.py – Validation engine implementing the six-step verification pipeline

• .claude-plugin/plugin.json – Version source of truth that must match headers in markdown files

Summary

• Exact extraction uses regex patterns ^### (\d+)\. and \| (\d+) \| to isolate identifiers from SKILL.md and README.md respectively.

• Strict range validation enforces contiguous numbering starting at 1 without gaps in the source file (lines 71-73).

• Bidirectional comparison ensures the README table contains exactly the same set of pattern numbers as the SKILL definition (lines 77-80).

• Automated header verification confirms the README summary reflects the actual pattern count extracted from the canonical source (line 81).

• Error messages specify exact mismatches, enabling rapid identification and correction of documentation drift.

Frequently Asked Questions

What regex patterns does the validator use to extract pattern numbers?

The validator uses ^### (\d+)\. to capture pattern identifiers from SKILL.md headings and \| (\d+) \| to extract numbers from README.md table rows. These patterns specifically target the markdown syntax used in each file to ensure accurate numeric extraction without false positives from other document content.

How does the validator handle duplicate pattern numbers?

The script detects duplicates during the bidirectional comparison phase (lines 77-80). Because it validates that the sorted readme_numbers list exactly matches pattern_numbers in length and content, any duplicate would cause a mismatch, triggering a SystemExit error indicating which patterns are missing or extraneous in the README tables.

Can the validator be integrated into CI/CD pipelines?

Yes, the script exits with a non-zero status code on validation failure, making it compatible with GitHub Actions, GitLab CI, or other automation platforms. The deterministic output format and specific error messages allow CI systems to parse failure types and provide targeted feedback to contributors.

What happens if the pattern count in the README header doesn't match the actual patterns?

Line 81 verifies the existence of ## The <n> patterns where <n> equals the total count of extracted patterns. If this header is missing or contains an incorrect number, the validator fails with a specific error indicating the discrepancy between the summary declaration and the actual pattern list extracted from SKILL.md.

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