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

> Explore the blader humanizer project's key files like SKILL.md and agents/openai.yaml. Understand AI prompts, agent integration, and validation logic with this file structure guide.

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

---

**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`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) specifically checks [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) into the agent's context.

```yaml

# 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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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.

```json
// .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`](https://github.com/blader/humanizer/blob/main/SKILL.md) matches the versions declared 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)
- Pattern headings in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) follow sequential numbering without gaps
- No duplicate patterns exist in the skill definition

Run the validator from the repository root:

```bash
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`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`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) to ensure consistency. It also validates that pattern headings in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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.