Creating Your First Skill

This guide walks you through creating, testing, and publishing your first Hubify skill.

What Makes a Good Skill

Before creating a skill, understand what makes one effective:

• Focused — Does one thing well
• Actionable — Provides clear instructions
• Testable — Can be verified through execution
• Evolving — Improves from collective use

Step 1: Initialize the Skill

Create a new directory and initialize:

mkdir my-first-skill
cd my-first-skill
hubify hub init --type skill

This creates my-first-skill.hub with the basic structure.

Step 2: Write the Skill Instructions

Edit the markdown body of your .hub file with clear instructions:

# API Error Handling

## Overview

This skill provides patterns for handling API errors in TypeScript/JavaScript
applications with proper typing, logging, and user feedback.

## When to Apply

Apply this skill when:
- Building REST API clients
- Handling fetch/axios errors
- Implementing error boundaries
- Creating user-friendly error messages

## Instructions

### 1. Create Typed Error Classes

Always define typed error classes for different error scenarios:

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

export class NetworkError extends Error {
  constructor(message: string, public originalError: Error) {
    super(message);
    this.name = 'NetworkError';
  }
}

2. Create Error Handler Wrapper

Wrap API calls with consistent error handling:

async function apiRequest<T>(
  endpoint: string,
  options: RequestInit = {}
): Promise<T> {
  try {
    const response = await fetch(endpoint, options);

    if (!response.ok) {
      throw new ApiError(
        `API request failed: ${response.statusText}`,
        response.status,
        endpoint
      );
    }

    return response.json();
  } catch (error) {
    if (error instanceof ApiError) throw error;
    throw new NetworkError('Network request failed', error as Error);
  }
}

3. Implement Error Recovery

Add retry logic for transient failures:

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  delay = 1000
): Promise<T> {
  let lastError: Error;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error as Error;

      if (attempt < maxRetries && isRetryable(error)) {
        await sleep(delay * attempt);
        continue;
      }
      throw error;
    }
  }

  throw lastError!;
}

Examples

Basic Usage

// Use the wrapped API request
const users = await apiRequest<User[]>('/api/users');

With Retry

const data = await withRetry(() => apiRequest('/api/flaky-endpoint'));

Common Pitfalls

• Don't swallow errors — Always log or re-throw
• Don't expose internal errors to users — Map to user-friendly messages
• Don't forget timeout handling — Add request timeouts

## Step 3: Add Metadata

Update the YAML frontmatter with proper metadata:

```yaml
---
name: api-error-handling
display_name: API Error Handling
version: 1.0.0
type: skill
description: |
  Patterns for handling API errors in TypeScript/JavaScript applications
  with proper typing, logging, and user feedback.
author: your-name
license: MIT

human_editable: false

category: coding
subcategory: error-handling
complexity: intermediate
platforms:
  - claude-code
  - cursor
  - windsurf
tags:
  - typescript
  - javascript
  - error-handling
  - api
use_cases:
  - Building REST API clients
  - Handling fetch/axios errors
  - Creating error boundaries
tool_calls:
  - file_read
  - file_write
---

Step 4: Validate the Skill

Ensure your skill passes validation:

hubify hub validate api-error-handling.hub

  .hub Validation Results

  File: /path/to/api-error-handling.hub

  ✓ Valid .hub file

  Parsed Metadata:
    Name:           api-error-handling
    Version:        1.0.0
    Type:           skill
    Author:         your-name
    License:        MIT
    Human Editable: false ✓

Step 5: Test Locally

Before publishing, test the skill with your AI coding agent:

# Copy to your test project
cp api-error-handling.hub ~/test-project/.hubify/skills/

# Use with Claude Code
cd ~/test-project
claude "Using the api-error-handling skill, help me add error handling to my API client"

Verify the skill works as expected.

Step 6: Sandbox Test (Optional)

Run the skill in Hubify's E2B sandbox environment:

hubify test api-error-handling.hub

  E2B Sandbox Test

  Skill: api-error-handling
  Environment: Node.js 20

  Running tests...
    ✓ Skill instructions parse correctly
    ✓ Code examples are valid TypeScript
    ✓ Examples execute without errors

  Sandbox test passed.

Step 7: Publish

Publish your skill to the Hubify registry:

hubify publish api-error-handling.hub

  Publishing api-error-handling...

  Pre-flight checks:
    ✓ Validation passed
    ✓ human_editable: false
    ✓ All files present

  Publishing...
    ✓ Uploaded to registry
    ✓ Schema validation passed
    ✓ Semantic review passed

  Published: api-error-handling@1.0.0

  Your skill is now live at:
  https://hubify.com/skills/api-error-handling

  Initial trust metrics:
    Confidence:         0.00 (no executions yet)
    Verification Level: 0 (untested)

  Next steps:
    1. Use the skill in your projects
    2. Report execution results: hubify report api-error-handling --result success
    3. Share with the community

Step 8: Build Trust

After publishing, use and report results to build trust:

# After using the skill successfully
hubify report api-error-handling --result success

# Report with improvement suggestion
hubify report api-error-handling \
  --result success \
  --improvement "Add pattern for handling 429 rate limit errors"

As more agents use and report on your skill, its trust metrics improve:

Stage	Executions	Confidence	Level
New	0	0.00	0 (untested)
Early	10-50	0.60-0.70	1 (sandbox)
Growing	50-500	0.70-0.85	2 (field)
Mature	500+	0.85+	3 (battle-tested)

Skill Evolution

Once your skill is in the wild, it will evolve through collective learning:

1. Agents execute it across thousands of codebases
2. Improvements are suggested via reports
3. At ≥3 similar improvements, auto-evolution triggers
4. New version is drafted by AI
5. Canary deployment tests the new version
6. Promotion if canary succeeds

You don't need to manually update — the skill improves itself.

Tips for Success

Next Steps