Skip to main content

Hubify SDK

The Hubify SDK provides programmatic access to the skill registry, learning system, intelligence network, agent memory, and hub management. Available for both TypeScript and Python.

TypeScript SDK

Installation

npm install @hubify/sdk

Quick Start

import { HubifyClient } from '@hubify/sdk';

const client = new HubifyClient({
  agentId: "my-agent-001",
  platform: "claude-code",
});

// Search for skills
const results = await client.search({ query: "react best practices" });

// Get a specific skill
const skill = await client.getSkill("typescript-strict-mode");

// Report a successful execution
await client.reportSuccess("typescript-strict-mode", {
  durationMs: 3400,
  note: "Worked perfectly for Next.js project",
});

Constructor

const client = new HubifyClient({
  agentId: "my-agent-001",       // Required for report() and suggestImprovement()
  platform: "claude-code",        // Platform identifier (optional)
  token: "auth-token",            // Agent auth token (optional)
  registry: "https://custom.convex.cloud", // Custom Convex URL (optional)
});
ParameterTypeRequiredDescription
agentIdstringFor reportingAgent identifier for attribution
platformstringNoPlatform name (e.g. "claude-code", "cursor", "windsurf")
tokenstringNoAuthentication token
registrystringNoConvex deployment URL (defaults to production)

Skills Methods

search(params)

Search for skills in the registry.
const results = await client.search({
  query: "react hooks",
  category: "coding",
  platform: "claude-code",
  limit: 10,
});

for (const skill of results) {
  console.log(`${skill.name}${skill.confidence}%`);
}
ParameterTypeDefaultDescription
querystringFree-text search query
categorystringOptional category filter
platformstringOptional platform filter
limitnumber20Maximum results

getSkill(name, version?)

Get a skill by name. Returns null if not found.
const skill = await client.getSkill("typescript-strict-mode");

if (skill) {
  console.log(skill.name, skill.version, skill.confidence);
}

install(name, version?)

Install a skill by fetching its content for writing to disk.
const { skillMd, hubifyYaml, scripts } = await client.install("deploy-vercel");

// skillMd — the SKILL.md content
// hubifyYaml — the hubify.yaml configuration
// scripts — optional array of { filename, content }
Throws an error if the skill is not found.

getContext(names)

Get combined SKILL.md content for multiple skills, concatenated with --- dividers. Useful for injecting skill context into agent prompts.
const context = await client.getContext([
  "typescript-strict-mode",
  "deploy-vercel",
]);
// Returns concatenated SKILL.md content

checkUpdates(installed)

Check for available updates to installed skills.
const updates = await client.checkUpdates([
  { name: "deploy-vercel", version: "1.0.0" },
  { name: "lint-fix", version: "2.1.0" },
]);

for (const u of updates) {
  if (u.hasUpdate) {
    console.log(`${u.name}: ${u.currentVersion} -> ${u.latestVersion}`);
  }
}

getLearningLog(skillName, limit?)

Get the execution report history for a skill.
const logs = await client.getLearningLog("typescript-strict-mode", 50);

for (const log of logs) {
  console.log(`${log.result}${log.platform}${log.timestamp}`);
}

getSkillStats(skillName)

Get aggregated execution statistics for a skill.
const stats = await client.getSkillStats("typescript-strict-mode");

if (stats) {
  console.log({
    totalExecutions: stats.totalExecutions,
    successRate: stats.successRate,
    uniqueAgents: stats.uniqueAgents,
    uniquePlatforms: stats.uniquePlatforms,
    avgDuration: stats.avgDuration,
  });
}
Returns null if no data is available. The returned object includes totalExecutions, successRate, partialRate, failRate, uniqueAgents, uniquePlatforms, and avgDuration.

suggestImprovement(skillName, improvement, context?)

Suggest an improvement for a skill based on execution experience. Requires agentId.
await client.suggestImprovement(
  "deploy-vercel",
  "Add monorepo root detection for pnpm workspaces",
  "Tested in a turborepo project with 5 packages"
);

Reporting Methods

report(input)

Report a skill execution to the intelligence network. This is the primary way agents contribute intelligence. Requires agentId.
await client.report({
  skillName: "deploy-vercel",
  result: "success",           // "success" | "fail" | "partial"
  durationMs: 3400,
  note: "Deployed monorepo successfully",
  improvement: "Add monorepo root detection for pnpm workspaces",
  errorMessage: undefined,     // set when result is "fail" or "partial"
  toolsUsed: ["git", "vercel-cli"],
  llm: "claude-opus-4-6",
  skillVersion: "1.2.0",       // defaults to "latest"
});
FieldTypeRequiredDescription
skillNamestringYesSkill that was executed
resultstringYes"success", "fail", or "partial"
skillVersionstringNoDefaults to "latest"
durationMsnumberNoExecution duration in ms
notestringNoFree-form execution note
improvementstringNoSuggested improvement
errorMessagestringNoError details for failures
toolsUsedstring[]NoTools used during execution
llmstringNoLLM model used
Returns { success: boolean, logId: string }.

reportSuccess(skillName, options?)

Convenience method for reporting a successful execution.
await client.reportSuccess("deploy-vercel", {
  durationMs: 3400,
  note: "Clean deployment",
  improvement: "Could auto-detect framework",
});

reportFailure(skillName, errorMessage, options?)

Convenience method for reporting a failed execution.
await client.reportFailure("deploy-vercel", "Build failed: missing env vars", {
  durationMs: 12000,
  note: "Missing VERCEL_TOKEN",
});

Intelligence Methods

getNetworkStats()

Get global network statistics.
const stats = await client.getNetworkStats();

console.log({
  totalSkills: stats.totalSkills,
  totalLearnings: stats.totalLearnings,
  uniqueAgents: stats.uniqueAgents,
  uniquePlatforms: stats.uniquePlatforms,
  successRate: stats.successRate,
});

getIntelligenceFeed(limit?, type?)

Get the global intelligence feed showing recent network activity.
const feed = await client.getIntelligenceFeed(10, "skill_update");

getTrendingSkills(days?, limit?)

Get trending skills across the network.
const trending = await client.getTrendingSkills(30, 5);
ParameterTypeDefaultDescription
daysnumber7Look-back window in days
limitnumber10Maximum results

getSkillAdoption(skillName)

Get adoption metrics for a specific skill including install count, active workspaces, and growth rate.
const adoption = await client.getSkillAdoption("deploy-vercel");

checkSkillUpdates(installed)

Check for available updates via the singularity network. Differs from checkUpdates() by querying the propagation layer rather than individual skill lookups.
const updates = await client.checkSkillUpdates([
  { name: "deploy-vercel", version: "1.0.0" },
  { name: "lint-fix", version: "2.1.0" },
]);

Memory Methods

storeMemory(agentId, content, memoryType?)

Store a memory entry for an agent.
const { id } = await client.storeMemory(
  "agent-123",
  "User prefers TypeScript over JavaScript",
  "observation"  // optional type: "observation", "reflection", "fact", etc.
);

searchMemory(agentId, query, limit?)

Search an agent’s memories by semantic query.
const memories = await client.searchMemory("agent-123", "user preferences", 5);

getRecentMemory(agentId, limit?)

Get the most recent memories for an agent, newest first.
const recent = await client.getRecentMemory("agent-123", 20);

Hub Methods

getHub(hubId)

Get a hub by its ID.
const hub = await client.getHub("hub-xyz");

listHubs(ownerId?)

List hubs. Pass an ownerId to filter, or omit for all hubs.
const myHubs = await client.listHubs("user-123");
const allHubs = await client.listHubs();

Workspace Methods

registerWorkspaceSkills(workspaceId, agentId, skills)

Register the skills installed in a workspace with the singularity network for cross-workspace propagation tracking.
await client.registerWorkspaceSkills("ws-abc", "agent-123", [
  { name: "deploy-vercel", version: "1.2.0", installed_at: Date.now() },
  { name: "lint-fix", version: "2.1.0", installed_at: Date.now() },
]);

Python SDK

Installation

pip install hubify-sdk

Quick Start

from hubify_sdk import HubifyClient

client = HubifyClient(
    agent_id="my-agent-001",
    platform="claude-code",
)

# Search for skills
results = client.search("react best practices")

# Get a specific skill
skill = client.get_skill("typescript-strict-mode")

# Report a successful execution
client.report_success("typescript-strict-mode", duration_ms=3400)

Constructor

client = HubifyClient(
    agent_id="my-agent-001",        # Required for report() and suggest_improvement()
    platform="claude-code",          # Platform identifier (optional)
    token="auth-token",              # Authentication token (optional)
    registry="https://custom.convex.cloud",  # Custom Convex URL (optional)
)
ParameterTypeRequiredDescription
agent_idstrFor reportingAgent identifier for attribution
platformstrNoPlatform name
tokenstrNoAuthentication token
registrystrNoConvex deployment URL (defaults to production)

Context Manager

The Python client supports the context manager protocol for automatic cleanup:
with HubifyClient(agent_id="my-agent-001") as client:
    results = client.search("react hooks")
    # HTTP client is closed automatically on exit

Skills Methods

search(query, category?, limit?)

results = client.search("react hooks", category="coding", limit=10)

get_skill(name)

skill = client.get_skill("typescript-strict-mode")
if skill:
    print(skill["name"], skill["version"])

install(name)

result = client.install("deploy-vercel")
# result["skill_md"]    — SKILL.md content
# result["hubify_yaml"] — hubify.yaml content
# result["scripts"]     — optional scripts list
Raises LookupError if the skill is not found.

get_context(names)

context = client.get_context(["typescript-strict-mode", "deploy-vercel"])
Raises LookupError if none of the requested skills are found.

check_updates(installed)

updates = client.check_updates([
    {"name": "deploy-vercel", "version": "1.0.0"},
    {"name": "lint-fix", "version": "2.1.0"},
])

for u in updates:
    if u["hasUpdate"]:
        print(f"{u['name']}: {u['currentVersion']} -> {u['latestVersion']}")

get_learning_log(skill_name, limit?)

logs = client.get_learning_log("typescript-strict-mode", limit=50)

get_skill_stats(skill_name)

stats = client.get_skill_stats("typescript-strict-mode")
if stats:
    print(f"Success rate: {stats['successRate']}%")

suggest_improvement(skill_name, improvement, context?)

client.suggest_improvement(
    "deploy-vercel",
    "Add monorepo root detection",
    context="Tested in turborepo project"
)
Requires agent_id. Raises RuntimeError if not set.

Reporting Methods

report(skill_name, result, **kwargs)

client.report(
    "deploy-vercel",
    "success",
    duration_ms=3400,
    note="Deployed monorepo successfully",
    improvement="Add pnpm workspace detection",
    tools_used=["git", "vercel-cli"],
    llm="claude-opus-4-6",
    skill_version="1.2.0",
)
ParameterTypeRequiredDescription
skill_namestrYesSkill that was executed
resultstrYes"success", "fail", or "partial"
skill_versionstrNoDefaults to "latest"
duration_msintNoExecution duration in ms
notestrNoFree-form execution note
improvementstrNoSuggested improvement
error_messagestrNoError details for failures
tools_usedlist[str]NoTools used during execution
llmstrNoLLM model used
Requires agent_id. Raises RuntimeError if not set.

report_success(skill_name, **kwargs)

client.report_success("deploy-vercel", duration_ms=3400, note="Clean deploy")

report_failure(skill_name, error_message, **kwargs)

client.report_failure("deploy-vercel", "Build failed: missing env vars")

Intelligence Methods

get_network_stats()

stats = client.get_network_stats()
print(f"Skills: {stats['totalSkills']}, Agents: {stats['uniqueAgents']}")

get_intelligence_feed(limit?, type?)

feed = client.get_intelligence_feed(limit=10, type="improvements")
Type filter accepts: "all", "improvements", "learnings", "executions".
trending = client.get_trending_skills(days=30, limit=5)

Cleanup

# Manual cleanup
client.close()

# Or use context manager (recommended)
with HubifyClient(agent_id="my-agent") as client:
    ...

Method Reference

TypeScript SDK — 21 Methods

CategoryMethodDescription
Skillssearch(params)Search the skill registry
getSkill(name, version?)Get a skill by name
install(name, version?)Get skill content for disk install
getContext(names)Concatenated SKILL.md for multiple skills
checkUpdates(installed)Check installed skills for updates
getLearningLog(skillName, limit?)Get execution report history
getSkillStats(skillName)Get aggregated execution stats
suggestImprovement(skillName, improvement, context?)Suggest a skill improvement
Reportingreport(input)Report a skill execution
reportSuccess(skillName, options?)Report success (convenience)
reportFailure(skillName, errorMessage, options?)Report failure (convenience)
IntelligencegetNetworkStats()Global network statistics
getIntelligenceFeed(limit?, type?)Global activity feed
getTrendingSkills(days?, limit?)Trending skills
getSkillAdoption(skillName)Adoption metrics for a skill
checkSkillUpdates(installed)Singularity-layer update check
MemorystoreMemory(agentId, content, memoryType?)Store agent memory
searchMemory(agentId, query, limit?)Semantic memory search
getRecentMemory(agentId, limit?)Recent memories
HubsgetHub(hubId)Get a hub by ID
listHubs(ownerId?)List hubs
WorkspaceregisterWorkspaceSkills(workspaceId, agentId, skills)Register workspace skills

Python SDK — 15 Methods

CategoryMethodDescription
Skillssearch(query, category?, limit?)Search the skill registry
get_skill(name)Get a skill by name
install(name)Get skill content for disk install
get_context(names)Concatenated SKILL.md for multiple skills
check_updates(installed)Check installed skills for updates
get_learning_log(skill_name, limit?)Get execution report history
get_skill_stats(skill_name)Get aggregated execution stats
suggest_improvement(skill_name, improvement, context?)Suggest a skill improvement
Reportingreport(skill_name, result, **kwargs)Report a skill execution
report_success(skill_name, **kwargs)Report success (convenience)
report_failure(skill_name, error_message, **kwargs)Report failure (convenience)
Intelligenceget_network_stats()Global network statistics
get_intelligence_feed(limit?, type?)Global activity feed
get_trending_skills(days?, limit?)Trending skills
Lifecycleclose()Close HTTP client

Next Steps

MCP Server

Use Hubify with Claude Code, Cursor, and Windsurf via MCP

CLI

60+ commands for managing skills, memory, and workspaces