@storyclaw/talenthub

CLI tool to manage StoryClaw AI agents — publish, install, update, export, and browse the TalentHub marketplace.

中文文档

Install

npm install -g @storyclaw/talenthub

Quick Start

# Login
talenthub login

# Initialize an agent
talenthub agent init --dir ~/.openclaw/workspace-my-agent

# Publish as public (default)
talenthub agent publish --dir ~/.openclaw/workspace-my-agent

# Or publish as private (only you can install)
talenthub agent publish --dir ~/.openclaw/workspace-my-agent --private

# Browse & install agents
talenthub agent search
talenthub agent install <agent-name>

Commands

| Command | Description | |---------|-------------| | talenthub login | Authenticate with StoryClaw | | talenthub logout | Remove stored credentials | | talenthub agent init | Initialize a new agent with manifest.json and prompt files | | talenthub agent publish | Publish a local agent to the registry (--private for private) | | talenthub agent unpublish <name> | Archive an agent from the registry | | talenthub agent visibility <name> | Toggle between public and private (--public / --private) | | talenthub agent install <name> | Install an agent with bundled skills | | talenthub agent update [name] | Update an agent or all (--all, --json), or manage its skills (--add-skill <zipUrl>, --remove-skill <name>, --force) | | talenthub agent uninstall <name> | Remove an installed agent | | talenthub agent list | List installed agents and check for updates | | talenthub agent search [query] | Browse available agents | | talenthub agent export <id> | Export an installed agent to a .zip file |

Agent Structure

A publishable agent directory contains prompts and bundled skills:

my-agent/
├── manifest.json          # Agent metadata (required)
├── IDENTITY.md            # Core identity
├── USER.md                # User-facing instructions
├── SOUL.md                # Personality and behavior
├── AGENTS.md              # Multi-agent coordination
└── skills/                # Bundled skills (optional)
    ├── pdf/
    │   └── SKILL.md
    └── web-search/
        ├── SKILL.md
        └── scripts/...

| File | Required | Description | |------|----------|-------------| | manifest.json | Required | Agent metadata (id, name, category, etc.) | | IDENTITY.md | Yes | Core identity and personality prompt | | USER.md | Optional | User-facing instructions | | SOUL.md | Optional | Deep personality and behavioral guidelines | | AGENTS.md | Optional | Multi-agent coordination instructions | | skills/<name>/ | Optional | Bundled skill directory (must contain SKILL.md) |

manifest.json

{
  "id": "my-agent",
  "name": "My Agent",
  "emoji": "🤖",
  "role": "Assistant",
  "tagline": "A helpful AI assistant",
  "description": "Longer description of what this agent does.",
  "category": "productivity",
  "i18n": {},
  "minOpenClawVersion": "2026.3.1"
}

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier (lowercase alphanumeric + hyphens) | | name | string | Human-readable display name | | emoji | string | Single emoji icon | | role | string | Short role description | | tagline | string | One-line summary for search results | | description | string | Longer description for detail page | | category | string | One of: creative, finance, productivity, companion, research, engineering | | i18n | object | Translations keyed by locale (zh-CN, zh-TW, ja) | | minOpenClawVersion | string | Minimum StoryClaw version required | | avatarUrl | string | null | Optional avatar image URL |

Notes:

• Version is not in the manifest — it is generated by the server.
• Skills are declared by folder presence in skills/, not listed in manifest.

Size Limits

• Each prompt file: 200 KB max
• Total prompts: 1 MB max
• Full zip package (prompts + skills): 50 MB max

Publishing

Publishing packages your agent directory into a zip and uploads it to S3. The zip contains your prompt files plus any skill folders under skills/.

# Public publish (default)
talenthub agent publish --dir /path/to/agent

# Private publish (only owner can install)
talenthub agent publish --dir /path/to/agent --private

# From an installed agent
talenthub agent publish --name my-agent

# From the current directory
talenthub agent publish

| Option | Description | |--------|-------------| | --dir <path> | Agent directory with manifest.json, prompts, and skills/ | | --name <name> | Agent name in openclaw config (resolves workspace dir) | | --id <id> | Override agent ID from manifest | | --private | Publish as a private agent (hidden from public catalog) |

Public vs Private

• Public agents appear in the catalog for anyone to install. The zip is served over CloudFront.
• Private agents are hidden from the public catalog. Only the owner (authenticated with th_* token) can install them. The zip is served via a short-lived presigned URL.

Switch visibility after publishing:

talenthub agent visibility my-agent --public   # private → public
talenthub agent visibility my-agent --private  # public → private

Installing

Public agents install without auth:

talenthub agent install my-agent

Private agents (your own) install with the saved login token automatically, or pass an explicit token:

talenthub agent install my-private-agent --token th_xxxxxxxx

Install downloads the zip and extracts prompts + bundled skills directly into the workspace. No GitHub cloning at install time.

Export

Export an installed agent to a local .zip (includes current workspace state, which may differ from the published version if you edited locally):

talenthub agent export my-agent              # writes my-agent.zip
talenthub agent export my-agent -o /tmp/x.zip
talenthub agent export my-agent --json       # structured output

Versioning

Versions are fully server-managed in YYYY.MM.DD-X format (e.g. 2026.04.13-1).

• New agent → YYYY.MM.DD-1
• Content change (any change that affects the zip content hash) → version auto-bumps
• Metadata-only change (only DB columns, zip unchanged) → version stays the same

Previous versions are automatically saved as snapshots.

Environment Variables

| Variable | Description | |----------|-------------| | TALENTHUB_URL | Override registry base URL (default: https://app.storyclaw.com) | | TALENTHUB_REGISTRY | Alias for TALENTHUB_URL |

Docs

• Publishing Guide (English)
• Publishing Guide (中文)

License

MIT

中文文档

StoryClaw AI Agent 管理工具 — 发布、安装、更新、导出和浏览 TalentHub 市场。

English

安装

npm install -g @storyclaw/talenthub

快速开始

# 登录
talenthub login

# 初始化 Agent
talenthub agent init --dir ~/.openclaw/workspace-my-agent

# 公开发布（默认）
talenthub agent publish --dir ~/.openclaw/workspace-my-agent

# 或私密发布（只有你可以安装）
talenthub agent publish --dir ~/.openclaw/workspace-my-agent --private

# 浏览和安装
talenthub agent search
talenthub agent install <agent-name>

命令列表

| 命令 | 说明 | |------|------| | talenthub login | 登录 StoryClaw | | talenthub logout | 退出登录 | | talenthub agent init | 初始化新 Agent（生成 manifest.json 和提示词文件） | | talenthub agent publish | 发布 Agent 到注册中心（加 --private 发布为私密） | | talenthub agent unpublish <name> | 下架 Agent | | talenthub agent visibility <name> | 切换公开/私密（--public / --private） | | talenthub agent install <name> | 安装 Agent（包含打包的技能） | | talenthub agent update [name] | 更新 Agent（--all 更新全部，--json 结构化输出），或管理技能（--add-skill <zipUrl>、--remove-skill <name>、--force） | | talenthub agent uninstall <name> | 卸载 Agent | | talenthub agent list | 列出已安装的 Agent | | talenthub agent search [query] | 搜索可用 Agent | | talenthub agent export <id> | 将已安装的 Agent 导出为 .zip 文件 |

Agent 目录结构

一个可发布的 Agent 目录包含提示词和打包的技能：

my-agent/
├── manifest.json          # Agent 元数据（必须）
├── IDENTITY.md            # 核心身份
├── USER.md                # 用户使用说明
├── SOUL.md                # 性格与行为
├── AGENTS.md              # 多 Agent 协作
└── skills/                # 打包技能（可选）
    ├── pdf/
    │   └── SKILL.md
    └── web-search/
        ├── SKILL.md
        └── scripts/...

| 文件 | 是否必须 | 说明 | |------|----------|------| | manifest.json | 必须 | Agent 元数据（ID、名称、分类等） | | IDENTITY.md | 必须 | 核心身份和人设提示词 | | USER.md | 可选 | 面向用户的使用说明 | | SOUL.md | 可选 | 深层性格和行为准则 | | AGENTS.md | 可选 | 多 Agent 协作指令 | | skills/<name>/ | 可选 | 打包的技能目录（须包含 SKILL.md） |

manifest.json

{
  "id": "my-agent",
  "name": "My Agent",
  "emoji": "🤖",
  "role": "Assistant",
  "tagline": "一句话描述你的 Agent",
  "description": "更详细的介绍。",
  "category": "productivity",
  "i18n": {},
  "minOpenClawVersion": "2026.3.1"
}

| 字段 | 类型 | 说明 | |------|------|------| | id | string | 唯一标识符，小写字母加连字符 | | name | string | 显示名称 | | emoji | string | 一个 emoji 图标 | | role | string | 角色简述 | | tagline | string | 一行摘要 | | description | string | 详细描述 | | category | string | creative、finance、productivity、companion、research、engineering | | i18n | object | 按语言代码存放翻译（zh-CN、zh-TW、ja） | | minOpenClawVersion | string | 最低 StoryClaw 版本 | | avatarUrl | string | null | 头像 URL（可选） |

注意：

• manifest 中没有 version 字段，版本由服务器自动生成。
• 技能通过 skills/ 下的文件夹声明，无需在 manifest 中列出。

发布

发布会把 Agent 目录打包成 zip 并上传到 S3。zip 包含提示词文件以及 skills/ 下的所有技能目录。

# 公开发布（默认）
talenthub agent publish --dir /path/to/agent

# 私密发布（只有作者本人可安装）
talenthub agent publish --dir /path/to/agent --private

# 从已安装的 Agent 发布
talenthub agent publish --name my-agent

# 从当前目录发布
talenthub agent publish

| 选项 | 说明 | |------|------| | --dir <path> | Agent 目录 | | --name <name> | openclaw 配置中的 Agent 名称 | | --id <id> | 覆盖 manifest 中的 Agent ID | | --private | 发布为私密（不在公开目录中出现） |

公开与私密

• 公开 Agent 出现在公共目录中，任何人可安装。zip 通过 CloudFront 分发。
• 私密 Agent 不在公共目录中。只有作者（使用 th_* token 登录）可以安装。zip 通过短时预签名链接分发。

发布后切换可见性：

talenthub agent visibility my-agent --public   # 私密 → 公开
talenthub agent visibility my-agent --private  # 公开 → 私密

安装

公开 Agent 无需鉴权：

talenthub agent install my-agent

私密 Agent（自己的）会自动使用已登录的 token，或传入显式 token：

talenthub agent install my-private-agent --token th_xxxxxxxx

安装时下载 zip 并直接解压提示词和打包的技能到工作区 — 安装过程中不再克隆 GitHub 仓库。

导出

把已安装的 Agent 导出为本地 .zip（包含当前工作区状态，可能与已发布版本不同，如果你做过本地修改）：

talenthub agent export my-agent              # 输出 my-agent.zip
talenthub agent export my-agent -o /tmp/x.zip
talenthub agent export my-agent --json       # 结构化输出

版本管理

版本完全由服务器管理，格式为 YYYY.MM.DD-X（如 2026.04.13-1）。

• 新 Agent → YYYY.MM.DD-1
• 内容变化（zip 内容 hash 变化）→ 版本自动递增
• 仅元数据变化（zip 内容未变，仅 DB 字段更新）→ 版本不变

每次版本递增时自动保存上一版本快照。

文件大小限制

• 单个提示词文件：最大 200 KB
• 所有提示词合计：最大 1 MB
• 整个 zip 包（提示词 + 技能）：最大 50 MB

环境变量

| 变量 | 说明 | |------|------| | TALENTHUB_URL | 覆盖注册中心地址（默认：https://app.storyclaw.com） | | TALENTHUB_REGISTRY | TALENTHUB_URL 的别名 |

详细文档

• 发布指南（中文）
• Publishing Guide (English)