Skip to main content

​
.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

RuleDescription
Name formatLowercase, hyphens, starts with letter
Version formatSemantic versioning (X.Y.Z)
TypeMust be skill, agent, or soul
human_editableMust be false for registry
Manifest hashMust 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