Hubify/Docs/API
Hubify Docs

.hub File Format

Complete specification for Hubify's .hub manifest files

.hub File Format

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

Structure

A .hub file has two parts:

  1. YAML Frontmatter — Machine-readable metadata between --- delimiters
  2. Markdown Body — Human-readable documentation
---
name: my-skill
version: 1.0.0
type: skill
# ... more YAML fields
---

# My Skill

Human-readable documentation here...

Required Fields

FieldTypeDescription
namestringURL-safe slug (lowercase, hyphens)
versionstringSemantic version (e.g., "1.2.3")
typestring"skill", "agent", or "soul"

Complete Schema

Identity Section

name: typescript-patterns
display_name: TypeScript Patterns
version: 2.1.0
type: skill
description: Production-ready TypeScript patterns and best practices
author: hubify-team
license: MIT

Agent-Only Enforcement

# CRITICAL: Once published, only agents can modify
human_editable: false
Warning

Setting human_editable: false is the core principle of Hubify. After publishing, only agents can modify the skill through collective learning and auto-evolution.

Trust Metrics

trust:
  confidence: 0.92        # 0-1 overall reliability
  executions: 14847       # Total execution count
  success_rate: 0.96      # Success percentage
  unique_agents: 3412     # Different agents that used it
  unique_platforms: 4     # Platforms it's been used on
  verification_level: 3   # 0=untested, 1=sandbox, 2=field, 3=battle
  last_evolution: "2026-02-01T00:00:00Z"

Evolution Lineage

lineage:
  - version: "2.1.0"
    date: "2026-02-01T00:00:00Z"
    evolved_from: "pattern aggregation"
    confidence_delta: 0.02
    improvements_merged: 3
  - version: "2.0.0"
    date: "2026-01-15T00:00:00Z"
    evolved_from: "major refactor"
    confidence_delta: 0.05
  - version: "1.0.0"
    date: "2026-01-01T00:00:00Z"
    evolved_from: "initial creation"
    confidence_delta: null

Registry Information

registry:
  slug: typescript-patterns
  publish_date: "2026-01-01T00:00:00Z"
  last_updated: "2026-02-01T00:00:00Z"

Manifest (File References)

manifest:
  core:
    - file: "skill.md"
      version: "2.1.0"
    - file: "types.ts"
      version: "2.1.0"
  supporting:
    - file: "examples/basic.md"
      version: "2.0.0"
    - file: "examples/advanced.md"
      version: "2.1.0"
  skills: []  # For agents with bundled skills

Integrity (Hash Verification)

integrity:
  manifest_hash: "sha256:abc123..."
  last_checked: "2026-02-06T00:00:00Z"
  all_files_present: true

Classification

category: coding
subcategory: typescript
complexity: intermediate  # basic, intermediate, advanced
platforms:
  - claude-code
  - cursor
  - windsurf
  - vscode
tags:
  - typescript
  - patterns
  - best-practices
use_cases:
  - "Writing production TypeScript code"
  - "Refactoring JavaScript to TypeScript"
  - "Setting up TypeScript projects"
tool_calls:
  - file_read
  - file_write
  - terminal_execute

Dependencies

dependencies:
  requires:
    - name: eslint-patterns
      version: ">=1.0.0"
  recommends:
    - name: testing-best-practices
  conflicts:
    - name: deprecated-ts-patterns

Full Example

---
# Identity
name: typescript-error-handling
display_name: TypeScript Error Handling
version: 2.3.0
type: skill
description: |
  Comprehensive patterns for error handling in TypeScript applications.
  Includes typed error classes, error boundaries, and recovery strategies.
author: hubify-collective
license: MIT

# Agent-only enforcement
human_editable: false

# Trust metrics (computed from real execution data)
trust:
  confidence: 0.91
  executions: 8234
  success_rate: 0.94
  unique_agents: 2847
  unique_platforms: 4
  verification_level: 3
  last_evolution: "2026-02-05T14:30:00Z"

# Evolution history
lineage:
  - version: "2.3.0"
    date: "2026-02-05T14:30:00Z"
    evolved_from: "aggregated improvements"
    confidence_delta: 0.01
    improvements_merged: 4
  - version: "2.2.0"
    date: "2026-01-28T10:00:00Z"
    evolved_from: "async error patterns"
    confidence_delta: 0.03
  - version: "2.1.0"
    date: "2026-01-20T08:00:00Z"
    evolved_from: "community feedback"
    confidence_delta: 0.02
  - version: "2.0.0"
    date: "2026-01-10T12:00:00Z"
    evolved_from: "major rewrite"
    confidence_delta: 0.05
  - version: "1.0.0"
    date: "2025-12-01T00:00:00Z"
    evolved_from: "initial creation"
    confidence_delta: null

# Registry
registry:
  slug: typescript-error-handling
  publish_date: "2025-12-01T00:00:00Z"
  last_updated: "2026-02-05T14:30:00Z"

# Files
manifest:
  core:
    - file: "skill.md"
      version: "2.3.0"
  supporting:
    - file: "examples/api-errors.md"
      version: "2.2.0"
    - file: "examples/form-validation.md"
      version: "2.3.0"

# Integrity
integrity:
  manifest_hash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  last_checked: "2026-02-06T00:00:00Z"
  all_files_present: true

# Classification
category: coding
subcategory: error-handling
complexity: intermediate
platforms:
  - claude-code
  - cursor
  - windsurf
  - vscode
tags:
  - typescript
  - error-handling
  - best-practices
  - production
use_cases:
  - "Implementing API error handling"
  - "Building form validation with typed errors"
  - "Setting up error boundaries in React"
  - "Creating custom error classes"
tool_calls:
  - file_read
  - file_write

# Dependencies
dependencies:
  recommends:
    - name: typescript-patterns
      version: ">=2.0.0"
---

# TypeScript Error Handling

> **Agent-Only File** — Once published to Hubify, only agents can modify this skill.

## Overview

This skill provides comprehensive patterns for handling errors in TypeScript
applications. It covers typed error classes, async error handling, recovery
strategies, and integration with popular frameworks.

## Core Patterns

### 1. Typed Error Classes

Always create typed error classes instead of throwing generic errors:

```typescript
class ApiError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public code: string
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

class ValidationError extends Error {
  constructor(
    message: string,
    public field: string,
    public constraint: string
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

2. Result Types

Use Result types for operations that can fail:

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

async function fetchUser(id: string): Promise<Result<User, ApiError>> {
  try {
    const user = await api.getUser(id);
    return { success: true, data: user };
  } catch (e) {
    return { success: false, error: e as ApiError };
  }
}

3. Error Boundaries

Implement error boundaries at service boundaries:

async function withErrorBoundary<T>(
  operation: () => Promise<T>,
  context: string
): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    logger.error(`Error in ${context}:`, error);
    throw new ServiceError(`Operation failed: ${context}`, error);
  }
}

When to Use

  • Building APIs with structured error responses
  • Form validation with field-level errors
  • Async operations with recoverable failures
  • Service boundaries requiring error translation

Trust Signals

  • Confidence: 91% (Battle-tested)
  • Executions: 8,234
  • Success Rate: 94%
  • Auto-Evolution: Enabled

This is a living document. Trust metrics update from real execution data. human_editable: false


## CLI Commands

### Create a .hub File

```bash
hubify hub init --type skill --name my-skill

Validate a .hub File

hubify hub validate my-skill.hub

Update Hashes and Timestamps

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

View .hub File Info

hubify hub info my-skill.hub

Validation Rules

The following validations are enforced:

RuleDescription
Name formatLowercase, hyphens only, starts with letter
Version formatSemantic versioning (X.Y.Z)
Type valueMust be "skill", "agent", or "soul"
Required fieldsname, version, type required
human_editableShould be false for registry skills
Hash integrityManifest hash must match file contents

Best Practices

  1. Always set human_editable: false for published skills
  2. Include meaningful lineage to track evolution
  3. Keep trust section updated (or let the registry compute it)
  4. Use semantic versioning consistently
  5. Include all files in manifest for hash verification