.hub Format

The .hub file is the manifest that defines a skill. This page documents the complete specification.

File Location

The .hub file should be at the root of your skill directory:

my-skill/
├── .hub           # Manifest file
├── prompt.md      # Optional: separate prompt file
└── examples/      # Optional: example files

Minimal Example

name: my-skill
version: 0.1.0
category: coding
description: A brief description
prompt: |
  Your skill instructions here...

Complete Specification

Core Fields

Field	Type	Required	Description
name	string	Yes	Unique skill identifier
version	string	Yes	Semver version (e.g., "1.0.0")
category	string	Yes	Skill category
description	string	Yes	Brief description (max 200 chars)
prompt	string	Yes*	Skill instructions
prompt_file	string	No	Path to external prompt file

*Either prompt or prompt_file is required.

Metadata Fields

Field	Type	Required	Description
author	string	No	Author identifier (@username)
license	string	No	License (MIT, Apache-2.0, etc.)
homepage	string	No	URL to documentation
repository	string	No	Source repository URL

Platform & Targeting

Field	Type	Required	Description
platforms	string[]	No	Supported platforms
use_cases	string[]	No	When to use this skill
tags	string[]	No	Searchable tags

Dependencies

Field	Type	Required	Description
dependencies.requires	string[]	No	Skills that must be installed
dependencies.extends	string[]	No	Skills this builds upon
dependencies.integrates_with	string[]	No	Compatible skills
dependencies.conflicts_with	string[]	No	Incompatible skills

Tools

Field	Type	Required	Description
tools.required	string[]	No	Required tool integrations
tools.optional	string[]	No	Optional tool integrations

Evolution

Field	Type	Required	Description
evolution.min_executions	number	No	Min executions before evolution
evolution.confidence_threshold	number	No	Min confidence to trigger
evolution.manual_approval	boolean	No	Require author approval
evolution.canary_duration	number	No	Canary test duration (hours)
evolution.scope	string[]	No	Allowed evolution types

Examples

Field	Type	Required	Description
examples	object[]	No	Usage examples
examples[].title	string	Yes	Example title
examples[].prompt	string	Yes	User prompt
examples[].expected	string	Yes	Expected outcome

Full Example

# Skill identity
name: typescript-strict-mode
version: 1.2.0
category: coding

# Metadata
author: "@houstongolden"
license: MIT
homepage: https://hubify.com/skills/typescript-strict-mode
repository: https://github.com/hubify/skills

# Description
description: |
  Enforce strict TypeScript configuration for improved type safety

# Targeting
platforms:
  - claude-code
  - cursor
  - windsurf

use_cases:
  - Configure tsconfig.json for strict mode
  - Add strict type checking rules
  - Enforce null checks
  - Migrate existing projects to strict TypeScript

tags:
  - typescript
  - configuration
  - type-safety
  - tsconfig

# Dependencies
dependencies:
  requires: []
  extends:
    - typescript-base-config
  integrates_with:
    - eslint-typescript
    - prettier-config
  conflicts_with:
    - typescript-loose-mode

# Tools
tools:
  required: []
  optional:
    - github  # For PR integration

# Evolution settings
evolution:
  min_executions: 100
  confidence_threshold: 0.85
  manual_approval: false
  canary_duration: 48
  scope:
    - prompt_refinement
    - example_addition
    - platform_compatibility

# The prompt
prompt: |
  When setting up TypeScript strict mode, follow these guidelines:

  ## Step 1: Enable Strict Mode

  Add or update your `tsconfig.json`:

  ```json
  {
    "compilerOptions": {
      "strict": true,
      "noUncheckedIndexedAccess": true,
      "exactOptionalPropertyTypes": true,
      "noImplicitReturns": true,
      "noFallthroughCasesInSwitch": true,
      "noImplicitOverride": true
    }
  }

Step 2: Handle Existing Errors

For existing projects with many type errors:

1. Start with strict: false
2. Enable flags incrementally
3. Use // @ts-expect-error sparingly

Step 3: Configure ESLint

Add TypeScript ESLint for runtime checks:

npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

Examples

examples:

• title: "New Next.js Project" prompt: "Set up strict TypeScript for my new Next.js app" expected: "Configure tsconfig.json with all strict flags enabled"

• title: "Existing Project Migration" prompt: "Migrate my existing project to strict TypeScript" expected: "Provide incremental migration strategy"

• title: "Monorepo Setup" prompt: "Configure strict TypeScript for a Turborepo monorepo" expected: "Set up base tsconfig with strict mode, extend in packages"

## Field Details

### name

Must be lowercase, alphanumeric with hyphens. 3-50 characters.

```yaml
# Valid
name: my-skill
name: typescript-strict-mode-v2

# Invalid
name: My Skill        # No spaces
name: mySkill         # No camelCase
name: ab              # Too short

version

Must follow semantic versioning:

version: 1.0.0    # Major.Minor.Patch
version: 0.1.0    # Pre-release
version: 2.0.0-beta.1  # Pre-release tag

category

One of the allowed categories:

category: coding        # Programming patterns
category: workflow      # Development workflows
category: documentation # Doc generation
category: testing       # Testing strategies
category: security      # Security practices
category: devops        # Deployment/infra
category: research      # Research/analysis

platforms

Supported AI agent platforms:

platforms:
  - claude-code
  - cursor
  - windsurf
  - copilot
  - cody
  - custom  # For custom implementations

prompt vs prompt_file

Either inline the prompt or reference an external file:

# Inline (recommended for short prompts)
prompt: |
  Your instructions here...

# External file (recommended for long prompts)
prompt_file: ./prompt.md

CLI Commands

Create .hub

hubify hub init

Interactive wizard to create a .hub file.

Validate

hubify hub validate ./my-skill

View Info

hubify hub info ./my-skill

Update Hashes

hubify hub update ./my-skill

Updates content hashes for integrity verification.

Best Practices

Organization

my-skill/
├── .hub              # Metadata only
├── prompt.md         # Main prompt
├── examples/
│   ├── basic.md
│   └── advanced.md
└── README.md         # For humans

Versioning

Bump versions appropriately:

• Patch (0.0.X): Typos, minor clarifications
• Minor (0.X.0): New examples, additional cases
• Major (X.0.0): Core prompt changes, breaking changes

Next Steps