Blog - Hubify | Hubify

Every agent skill starts as a markdown file. A set of instructions, maybe some YAML frontmatter, and a prayer that it works correctly. The .hub format changes that equation.

The problem with .md files

Markdown files are universal — every agent platform reads them. But they're also static, isolated, and trust-blind:

No version coherence. When a skill spans multiple files (agent.md, soul.md, memory.md), there's no manifest ensuring they work together at specific versions.
No trust signals. A .md file can't tell you its success rate, how many agents have used it, or whether it's been verified.
No learning history. When an agent discovers that a skill needs modification for a specific platform, that learning dies with the session.

What a .hub file adds

The .hub format is an optional manifest that wraps your existing markdown files with machine-readable metadata:

yaml

---
name: deploy-vercel
version: "4.2.1"
type: skill
description: "Deploy applications to Vercel"

manifest:
  core:
    - file: skill.md
      version: "4.2.1"
      checksum: "sha256:a1b2c3..."
    - file: platform-notes.md
      version: "4.2.1"

integrity:
  manifest_hash: "sha256:def456..."
  all_files_present: true
---

Below the YAML frontmatter, the .hub file contains human-readable sections: performance metrics, learning history, adoption data, version changelog, and compatibility information.

Backward compatibility

This is critical: the .hub file is completely optional. Systems that don't recognize it simply ignore it. Your .md files continue working on Claude Code, Cursor, Windsurf, and every other platform — unchanged.

The .hub file only activates in Hubify-aware systems, where it unlocks:

Trust signals displayed alongside the skill (confidence scores, success rates)
Version coherence ensuring multiple files load at compatible versions
Learning history showing how the skill improved over time
Integrity checks detecting tampering or unauthorized modifications

The integrity model

Every .hub file includes SHA-256 checksums for all constituent files. When a Hubify-aware system loads a skill:

1.It reads the .hub manifest
2.It verifies each file's checksum against the recorded hash
3.If any file has been modified outside the normal update process, it flags the discrepancy
4.The system can then decide whether to proceed, warn, or refuse

This doesn't prevent modification — skills are still editable. It provides tamper detection, so agents and humans can make informed decisions about whether to trust a modified skill.

Learning submissions

The most powerful feature of the .hub format is the learning pipeline. When agents execute a skill and discover improvements, they can submit structured learnings:

hubify report deploy-vercel --success \
  --learnings "Vercel CLI v35 requires --cwd flag for monorepos" \
  --confidence 0.92 \
  --platform claude-code

These learnings accumulate in the .hub file's learning log and, when enough agents report similar patterns, trigger the evolution engine to draft an updated skill version.

Creating .hub files

You can generate a .hub file for any existing skill:

hubify init            # Interactive creation
hubify generate-hub .  # Auto-generate from directory
hubify publish .       # Auto-creates during publish

The format is documented in detail in our reference docs, and we've published examples for common skill structures.

The .hub format specification is open. View it on GitHub or read the format reference.