Key Files in the blader/humanizer Project: A Complete File Structure Guide

The blader/humanizer repository contains eight essential files—including SKILL.md, agents/openai.yaml, and scripts/validate-package.py—that collectively define the skill's AI prompts, cross-platform agent integration, and package validation logic.

The blader/humanizer project is a portable skill for AI agents that transforms robotic text into natural human prose. Understanding the key files in this repository is critical for developers integrating the skill into OpenAI-compatible or Claude environments, as well as contributors maintaining package consistency.

Core Skill Definition: SKILL.md

The SKILL.md file serves as the single source of truth for the humanizer skill. Located at the repository root, this markdown file contains portable YAML metadata—including the version number and description—followed by the complete prompt that agents read to "humanize" text.

All patterns, examples, and guidelines for modifying AI-generated text reside in this file. The validation logic in scripts/validate-package.py specifically checks SKILL.md for proper heading numbering, version consistency, and sequential pattern ordering. When you modify this file, you directly alter what the skill teaches agents across all platforms.

Agent Integration Configuration

OpenAI-Compatible Integration: agents/openai.yaml

The agents/openai.yaml file provides the wrapper necessary for OpenAI-compatible platforms to discover and load the skill. This YAML configuration specifies the displayName, description, and crucially, the defaultPrompt directive that injects the contents of SKILL.md into the agent's context.

# agents/openai.yaml (excerpt)

displayName: Humanizer
description: |
  A skill that explains why AI‑generated text sounds the way it does and
  provides patterns to make it sound more human.
defaultPrompt: |
  {{ readFile "SKILL.md" }}

When an OpenAI-compatible agent reads this file, it automatically loads the full humanizer knowledge base from SKILL.md, eliminating the need for manual prompt engineering.

Claude Platform Integration: .claude-plugin/plugin.json

For Claude-specific deployments, the .claude-plugin/plugin.json file acts as the plugin descriptor. It maps the Claude plugin loader to SKILL.md and records the skill's version number, enabling local plugin loading and marketplace distribution.

Claude Marketplace Metadata: .claude-plugin/marketplace.json

The .claude-plugin/marketplace.json file contains publishing metadata required for the Claude marketplace, including author information, searchable tags, and the public description. This JSON facilitates discovery and installation through Claude's UI.

// .claude-plugin/marketplace.json (excerpt)
{
  "name": "Humanizer",
  "author": "blader",
  "tags": ["writing", "style", "prompt"],
  "description": "Explain why AI text sounds the way it does and provide patterns to make it sound human."
}

Validation and Quality Assurance

Package Validation Script: scripts/validate-package.py

The scripts/validate-package.py script enforces package-level invariants before publication. This Python validator ensures that:

• The metadata.version field in SKILL.md matches the versions declared in README.md and .claude-plugin/plugin.json
• Pattern headings in SKILL.md follow sequential numbering without gaps
• No duplicate patterns exist in the skill definition

Run the validator from the repository root:

python3 scripts/validate-package.py

If any check fails, the script exits with a non-zero status, preventing broken releases from reaching production.

Contributor Guidelines: AGENTS.md

The AGENTS.md file provides internal documentation for developers modifying the skill without breaking cross-platform compatibility. It documents naming conventions, version synchronization procedures, and validation steps required before submitting changes.

Documentation and Legal Structure

User Documentation: README.md

The README.md file contains human-readable installation instructions, usage examples for different agents, and a comprehensive version history table. This file keeps end-users and contributors aligned on current capabilities and changelog information.

License: LICENSE

The LICENSE file distributes the skill under MIT terms, clarifying usage rights for downstream commercial and non-commercial users.

Summary

• SKILL.md functions as the central source of truth, containing the YAML metadata and prompts that define the humanizer behavior.
• agents/openai.yaml enables OpenAI-compatible agents to load the skill via a standardized wrapper configuration.
• .claude-plugin/plugin.json and marketplace.json handle Claude-specific integration and marketplace discovery.
• scripts/validate-package.py maintains package integrity by enforcing version consistency and pattern validation.
• AGENTS.md provides the contributor guidelines necessary for safe repository modifications.
• README.md and LICENSE supply user documentation and legal distribution terms.

Frequently Asked Questions

What is the purpose of SKILL.md in the blader/humanizer project?

SKILL.md serves as the portable source of truth containing both the YAML metadata (version, description) and the actual prompt content that teaches agents how to humanize text. All agent integrations—including OpenAI and Claude—ultimately read this file to access the skill's functionality.

How does scripts/validate-package.py ensure package integrity?

The scripts/validate-package.py validator cross-references version numbers across SKILL.md, README.md, and .claude-plugin/plugin.json to ensure consistency. It also validates that pattern headings in SKILL.md are sequentially numbered without duplicates, exiting with a non-zero error code if any invariant is violated.

What is the difference between plugin.json and marketplace.json?

The .claude-plugin/plugin.json file is a technical descriptor that tells the Claude plugin loader where to find SKILL.md and what version to report. The marketplace.json file contains marketing metadata—author name, tags, and descriptions—used for discovery and display within the Claude marketplace interface.

How do I integrate this skill with an OpenAI-compatible agent?

Configure your agent to read the agents/openai.yaml file, which contains a defaultPrompt directive that loads SKILL.md using the {{ readFile "SKILL.md" }} template syntax. This automatically injects the complete humanizer prompt into the agent's context without manual copy-pasting.

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