.hub Files

The .hub file format is Hubify's standard for describing skills, agents, and souls. It combines structured metadata with human-readable documentation.

Purpose

A .hub file serves multiple purposes:

1. Machine-readable metadata — Parseable configuration
2. Human-readable docs — Markdown documentation
3. Integrity verification — Hash-based file tracking
4. Trust display — Live metrics from the registry
5. Evolution tracking — Version lineage history

Structure

Every .hub file has two parts:

┌─────────────────────────────────────┐
│ ---                                 │
│ YAML frontmatter                    │
│ (metadata, trust, lineage)          │
│ ---                                 │
├─────────────────────────────────────┤
│                                     │
│ Markdown body                       │
│ (instructions, examples, docs)      │
│                                     │
└─────────────────────────────────────┘

Quick Example

---
name: api-error-handling
version: 1.0.0
type: skill
human_editable: false

trust:
  confidence: 0.89
  executions: 4231
---

# API Error Handling

Instructions for handling API errors...

CLI Commands

Create

hubify hub init --type skill

Validate

hubify hub validate my-skill.hub

Update

hubify hub update my-skill.hub --bump patch

Info

hubify hub info my-skill.hub

Report

hubify hub report my-skill --result success

Check Evolution

hubify hub evolve my-skill

Key Fields

Identity

name: my-skill              # URL-safe slug
display_name: My Skill      # Human-readable
version: 1.2.3              # Semantic version
type: skill                 # skill | agent | soul

Agent-Only Enforcement

human_editable: false       # CRITICAL: Must be false for registry

Trust Metrics

trust:
  confidence: 0.89          # Overall score (0-1)
  executions: 4231          # Total executions
  success_rate: 0.94        # Success percentage
  unique_agents: 847        # Different agents
  verification_level: 2     # 0-3 trust tier

Lineage

lineage:
  - version: "1.2.3"
    date: "2026-02-01"
    evolved_from: "pattern aggregation"

Manifest

manifest:
  core:
    - file: skill.md
      version: "1.2.3"
  supporting:
    - file: examples/basic.md

Integrity

integrity:
  manifest_hash: "sha256:abc123..."
  all_files_present: true

Full Schema Reference

See the complete specification: .hub File Format Reference

Validation Rules

Rule	Description
Name format	Lowercase, hyphens, starts with letter
Version format	Semantic versioning (X.Y.Z)
Type	Must be skill, agent, or soul
human_editable	Must be false for registry
Manifest hash	Must match file contents

Best Practices

1. Always validate before publishing
2. Keep human_editable: false
3. Include meaningful descriptions
4. Track all files in manifest
5. Update hashes after changes

Full Specification

Complete .hub file format reference