Skills are .hub YAML files that teach AI agents how to perform specific tasks. This guide walks you through creating one from scratch, testing it locally, and publishing it to the Hubify registry.
This scaffolds a api-error-handling.hub file with the required structure.
2
Define the YAML frontmatter
Open the .hub file and fill in the metadata. Every field in the YAML block tells the registry and other agents what this skill does, who wrote it, and where it applies.
---name: api-error-handlingdisplay_name: API Error Handlingversion: 1.0.0type: skilldescription: | Patterns for handling API errors in TypeScript/JavaScript applications with proper typing, logging, and user feedback.author: your-usernamelicense: MIThuman_editable: falsecategory: codingsubcategory: error-handlingcomplexity: intermediateplatforms: - claude-code - cursor - windsurftags: - typescript - javascript - error-handling - apiuse_cases: - Building REST API clients - Handling fetch/axios errors - Creating error boundariestool_calls: - file_read - file_write---
human_editable: false is required for publishing. This tells the registry that the skill is agent-executable, not a human-editable document.
3
Write the skill instructions
Below the YAML frontmatter, write the markdown body. This is what agents read when they execute the skill. Be specific, include real code, and handle edge cases.
# API Error Handling## OverviewThis skill provides patterns for handling API errors in TypeScript/JavaScriptapplications with proper typing, logging, and user feedback.## When to ApplyApply this skill when:- Building REST API clients- Handling fetch/axios errors- Implementing error boundaries- Creating user-friendly error messages## Instructions### 1. Create Typed Error ClassesAlways define typed error classes for different error scenarios:\`\`\`typescriptexport 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 WrapperWrap API calls with consistent error handling:\`\`\`typescriptasync 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 Retry LogicAdd retry logic for transient failures:\`\`\`typescriptasync 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!;}\`\`\`## Common Pitfalls- Do not swallow errors silently -- always log or re-throw- Do not expose internal error details to end users -- map to friendly messages- Do not forget request timeouts -- add AbortController for every fetch call
4
Validate the skill
Run the validator to make sure the .hub file is structurally correct before publishing.
Before publishing, verify the skill works with your agent. Copy it into your workspace skills directory and use it.
# Copy into your workspacecp api-error-handling.hub ~/my-workspace/skills/api-error-handling/# Use with Claude Code (or your preferred agent)cd ~/my-workspaceclaude "Using the api-error-handling skill, add error handling to src/api/client.ts"
Verify the agent follows the instructions correctly and produces the expected code patterns.
6
Run sandbox test (optional)
Hubify provides E2B sandbox environments for automated skill testing. This runs the skill in an isolated container and validates that code examples compile and execute.
hubify test api-error-handling.hub
E2B Sandbox Test Skill: api-error-handling Environment: Node.js 22 Running tests... ✓ Skill instructions parse correctly ✓ Code examples are valid TypeScript ✓ Examples execute without errors Sandbox test passed.
7
Publish to the registry
When you are satisfied the skill works, publish it.
hubify publish api-error-handling.hub
The skill goes through the 5-gate Trust Gateway:
Schema validation — YAML structure and required fields
Provenance verification — author identity check
Content security scan — prompt injection, malware, data exfiltration patterns
Reputation check — author history and trust score
E2B sandbox test — automated execution in isolated environment
Publishing api-error-handling... Trust Gateway: ✓ Gate 1: Schema validation passed ✓ Gate 2: Provenance verified ✓ Gate 3: Content security scan clean ✓ Gate 4: Reputation check passed ✓ Gate 5: Sandbox test 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)
8
Build trust through execution reports
After publishing, use the skill in real projects and report results. Every report from every agent builds the skill’s confidence score.
# Report a successful executionhubify report api-error-handling --result success# Report with an improvement suggestionhubify report api-error-handling \ --result success \ --improvement "Add pattern for handling 429 rate limit errors with exponential backoff"
Be specific in your instructions. Vague guidance like “handle errors properly” leads to inconsistent results. Include concrete code examples with actual function signatures.
Always include a “When to Apply” section. This helps agents decide whether your skill is relevant to the current task before they load the full instructions.
Document common pitfalls. Agents learn from negative patterns just as much as positive ones.
Test across platforms. A skill that works on Claude Code might need adjustments for Cursor or Windsurf. Specify supported platforms in the platforms field.
