skill-publish-guide（技能发布指南）

ClawHub Publisher - Publish & Manage Skills on ClawHub

ClawHub 发布器 - 在 ClawHub 上发布和管理技能

Prerequisites / 前提条件

1. clawhub CLI must be installed. Verify with clawhub -V.

clawhub CLI 必须已安装。用 clawhub -V 验证。

1. You must be logged in. Check with clawhub whoami. If not logged in, run clawhub login.

必须已登录。用 clawhub whoami 检查。未登录则运行 clawhub login。

1. GitHub account must be at least 1 week old to publish.

GitHub 账户需创建至少一周才能发布。

SKILL.md Format / SKILL.md 格式

Every skill must have a SKILL.md file with YAML frontmatter: 每个技能必须包含带 YAML frontmatter 的 SKILL.md 文件：

---
name: my-skill
description: "Short description of what this skill does / 技能简短描述"
env:
  MY_API_KEY: "Optional. Description of the env var / 可选。环境变量说明"
always: false
---

# Skill Title

Instructions and documentation here...

Frontmatter Fields / Frontmatter 字段

Directory Structure / 目录结构

my-skill/
├── SKILL.md          # Required / 必需
├── scripts/          # Optional, helper scripts / 可选，辅助脚本
├── rules/            # Optional, reference files / 可选，参考文件
└── ...

Important / 注意:

• Do NOT include .git, LICENSE, .DS_Store, or binary files / 不要包含 .git、LICENSE、.DS_Store 或二进制文件
• Only text files are allowed / 只允许文本文件

Publishing Workflow / 发布流程

Step 1: Prepare / 准备

Ensure the skill folder contains a valid SKILL.md with proper frontmatter. 确保技能文件夹包含有效的 SKILL.md 和正确的 frontmatter。

Step 2: Validate / 验证

Before publishing, verify: 发布前验证以下内容：

• [ ] name in frontmatter matches the --slug you plan to use / frontmatter 中的 name 与计划的 --slug 一致
• [ ] description is clear and includes trigger keywords / description 清晰且包含触发关键词
• [ ] All env vars used in commands are declared in env section / 命令中使用的环境变量都在 env 中声明
• [ ] No binary files, .git, or LICENSE in the folder / 文件夹中无二进制文件、.git 或 LICENSE
• [ ] No interactive prompts (AI Agent cannot answer y/n) / 无交互式提示（AI Agent 无法回答 y/n）

Step 3: Publish / 发布

clawhub publish <path> \
  --slug <slug> \
  --name "<Display Name>" \
  --version <semver> \
  --tags latest \
  --no-input

Parameters / 参数:

Example / 示例:

clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --tags latest \
  --no-input

Step 4: Verify / 确认

After publishing, the skill enters security scan (usually takes a few minutes): 发布后技能进入安全扫描（通常需要几分钟）：

# Check skill status / 检查技能状态
clawhub inspect <slug>

If you see "Skill is hidden while security scan is pending", wait and retry. 如果看到"Skill is hidden while security scan is pending"，等待后重试。

Updating a Skill / 更新技能

To update, publish with an incremented version number: 更新时需升级版本号：

clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.1 \
  --tags latest \
  --no-input

Important / 注意: The same version cannot be republished. If you delete a skill and republish, you must use a new version number. 同一版本号不可重复发布。删除后重新发布也必须使用新版本号。

Deleting a Skill / 删除技能

clawhub delete <slug> --yes

Warning / 警告: Deletion is soft-delete. After deletion, the same version number cannot be reused for the same slug. 删除为软删除。删除后同一 slug 的同一版本号不可复用。

Common Issues & Solutions / 常见问题与解决

Security Best Practices / 安全最佳实践

When writing a SKILL.md, follow these guidelines to pass ClawHub security review: 编写 SKILL.md 时，遵循以下准则以通过 ClawHub 安全审核：

1. Declare all env vars / 声明所有环境变量: If any command requires an API key or secret, declare it in the env section of frontmatter. Explain what it's for and whether it's optional.

如果命令需要 API key 或密钥，在 frontmatter 的 env 中声明，说明用途和是否可选。

1. Avoid curl|bash as primary install method / 避免将 curl|bash 作为主要安装方式: Recommend Homebrew, Scoop, or source build first. If including a curl|bash script, add a security warning.

优先推荐 Homebrew、Scoop 或源码构建。如包含 curl|bash 脚本，添加安全提示。

1. No interactive prompts / 无交互提示: AI Agents cannot answer y/n questions. All operations must be completable via command-line arguments.

AI Agent 无法回答 y/n 问题。所有操作必须能通过命令行参数完成。

1. Document network operations / 说明网络操作: If the skill includes HTTP requests, DNS lookups, port scanning, etc., note this clearly so users are aware.

如果技能包含 HTTP 请求、DNS 查询、端口扫描等，明确说明让用户知晓。

1. Document credential storage / 说明凭据存储: If the skill stores secrets locally (password vault, API keys), explain the encryption method and storage location.

如果技能在本地存储密钥（密码保险库、API key），说明加密方式和存储位置。

1. No binary files in skill bundle / 技能包中不含二进制文件: Only include text files (Markdown, JSON, YAML, scripts). Binary files will be rejected.

只包含文本文件（Markdown、JSON、YAML、脚本）。二进制文件会被拒绝。

CLI Reference / CLI 命令参考

# Authentication / 认证
clawhub login                           # Login via browser / 浏览器登录
clawhub login --token <token>           # Login with API token / 用 API token 登录
clawhub logout                          # Logout / 登出
clawhub whoami                          # Check current identity / 查看当前身份

# Publish / 发布
clawhub publish <path> --slug <slug> --name "<name>" --version <ver>
                                        # Publish a skill / 发布技能

# Verify / 确认
clawhub inspect <slug>                  # View skill metadata / 查看技能元数据

# Delete & Restore / 删除与恢复
clawhub delete <slug> --yes             # Soft-delete a skill / 软删除技能
clawhub undelete <slug>                 # Restore deleted skill / 恢复已删除技能

# Batch / 批量
clawhub sync --all                      # Sync all local skills / 同步所有本地技能
clawhub sync --dry-run                  # Preview without uploading / 预览不上传