目录
-
- 摘要
- [1. 引言](#1. 引言)
- [2. ClawHub 技能市场介绍](#2. ClawHub 技能市场介绍)
-
- [2.1 什么是 ClawHub](#2.1 什么是 ClawHub)
- [2.2 ClawHub 的核心价值](#2.2 ClawHub 的核心价值)
- [2.3 技能市场架构](#2.3 技能市场架构)
- [2.4 ClawHub CLI 工具](#2.4 ClawHub CLI 工具)
- [3. 技能打包规范](#3. 技能打包规范)
- [4. 版本管理策略](#4. 版本管理策略)
-
- [4.1 语义化版本控制](#4.1 语义化版本控制)
- [4.2 版本更新规则](#4.2 版本更新规则)
- [4.3 变更日志规范](#4.3 变更日志规范)
- [4.4 版本发布流程](#4.4 版本发布流程)
- [5. 发布流程详解](#5. 发布流程详解)
-
- [5.1 发布前准备](#5.1 发布前准备)
-
- [5.1.1 注册 ClawHub 账号](#5.1.1 注册 ClawHub 账号)
- [5.1.2 验证技能结构](#5.1.2 验证技能结构)
- [5.2 发布命令详解](#5.2 发布命令详解)
- [5.3 完整发布示例](#5.3 完整发布示例)
- [5.4 发布后验证](#5.4 发布后验证)
- [5.5 发布常见问题](#5.5 发布常见问题)
- [6. 技能文档编写](#6. 技能文档编写)
- [7. 社区贡献指南](#7. 社区贡献指南)
-
- [7.1 贡献方式](#7.1 贡献方式)
- [7.2 贡献流程](#7.2 贡献流程)
- [7.3 Pull Request 规范](#7.3 Pull Request 规范)
- [7.4 代码审查标准](#7.4 代码审查标准)
- [7.5 社区行为准则](#7.5 社区行为准则)
- [8. 最佳实践](#8. 最佳实践)
-
- [8.1 技能设计原则](#8.1 技能设计原则)
- [8.2 性能优化建议](#8.2 性能优化建议)
- [8.3 安全性考虑](#8.3 安全性考虑)
- [8.4 版本兼容性维护](#8.4 版本兼容性维护)
- [8.5 持续集成建议](#8.5 持续集成建议)
- [8.6 发布节奏建议](#8.6 发布节奏建议)
- [9. 实战案例：发布一个完整技能](#9. 实战案例：发布一个完整技能)
-
- [9.1 案例背景](#9.1 案例背景)
- [9.2 技能结构](#9.2 技能结构)
- [9.3 核心代码](#9.3 核心代码)
- [9.4 发布过程](#9.4 发布过程)
- [9.5 发布后维护](#9.5 发布后维护)
- [10. 总结](#10. 总结)
- 参考资料
摘要
本文深入探讨 OpenClaw 技能生态的核心组成部分------技能发布与共享机制。从 ClawHub 技能市场的架构设计出发，详细讲解技能打包规范、版本管理策略、发布流程以及技能文档编写的最佳实践。通过真实案例和代码示例，读者将掌握如何将自己开发的技能发布到社区，实现技能的共享与协作。无论你是初入 OpenClaw 生态的新手，还是希望为社区贡献力量的资深开发者，本文都将为你提供从技能开发到社区发布的完整路线图。
1. 引言
在 AI Agent 开发领域，技能（Skill）系统是区分框架能力的关键因素。OpenClaw 通过其独特的技能架构，让开发者能够像搭积木一样扩展 AI Agent 的能力边界。然而，技能的价值不仅在于开发，更在于共享------当一个技能被社区广泛使用和改进时，它才能发挥最大的价值。
ClawHub 作为 OpenClaw 官方的技能市场，为技能的发布、发现和共享提供了标准化的平台。本文将从实践角度出发，系统性地介绍技能发布的完整流程，帮助开发者将自己的创意转化为社区共享的资源。
2. ClawHub 技能市场介绍
2.1 什么是 ClawHub
ClawHub 是 OpenClaw 官方运营的技能市场平台，类似于 npm 之于 Node.js、PyPI 之于 Python。它为 OpenClaw 技能提供了一个中心化的分发渠道，让开发者可以轻松地发布、更新和分享自己开发的技能。
2.2 ClawHub 的核心价值
ClawHub 的设计理念围绕三个核心价值展开：
| 价值维度 | 具体体现 | 用户收益 |
|---|---|---|
| 发现性 | 搜索引擎、分类标签、热门推荐 | 快速找到所需技能 |
| 可靠性 | 版本管理、变更日志、作者认证 | 安心使用稳定版本 |
| 协作性 | Fork、PR、社区讨论 | 参与技能改进 |
2.3 技能市场架构
ClawHub 采用现代化的微服务架构，确保高可用性和快速响应：
💾 存储层
⚙️ 服务层
👤 用户层
开发者
ClawHub CLI
使用者
Web界面
API Gateway
认证服务
技能索引
版本管理
技能元数据
技能包存储
用户数据
2.4 ClawHub CLI 工具
ClawHub 提供了功能完善的命令行工具，让开发者可以完全通过终端完成技能的搜索、安装和发布：
bash
# 安装 ClawHub CLI
npm install -g clawhub
# 查看帮助信息
clawhub --help
# 查看当前登录状态
clawhub whoamiCLI 工具的核心命令包括：
| 命令 | 功能 | 使用场景 |
|---|---|---|
search |
搜索技能 | 发现新技能 |
install |
安装技能 | 获取技能到本地 |
update |
更新技能 | 升级到新版本 |
list |
列出已安装技能 | 管理本地技能 |
publish |
发布技能 | 分享到社区 |
login |
登录认证 | 发布前准备 |
3. 技能打包规范
3.1 技能目录结构
一个标准的 OpenClaw 技能应遵循以下目录结构：
my-skill/
├── SKILL.md # 技能主文件（必需）
├── README.md # 技能说明文档
├── package.json # 技能元数据（可选）
├── scripts/ # 可执行脚本
│ ├── helper.py
│ └── utils.sh
├── references/ # 参考文档
│ ├── api.md
│ └── examples.md
├── assets/ # 静态资源
│ ├── logo.png
│ └── templates/
└── tests/ # 测试用例
└── test_cases.json3.2 SKILL.md 文件规范
SKILL.md 是技能的核心文件，包含 YAML 前置元数据和 Markdown 格式的指令内容：
yaml
---
name: weather-forecast
description: 获取天气信息和天气预报。当用户询问天气、温度、降雨等气象相关问题时使用此技能。
metadata:
openclaw:
requires:
bins: ["curl"]
env: ["WEATHER_API_KEY"]
install:
- id: python-requests
kind: pip
package: requests
label: 安装 Python requests 库
---
# 天气预报技能
本技能为 OpenClaw 提供天气查询和预报功能。
## 功能特性
- 实时天气查询
- 多日天气预报
- 城市天气对比
- 天气预警提醒
## 使用方法
当用户询问天气时，按以下步骤操作：
1. 解析用户提供的城市名称
2. 调用天气 API 获取数据
3. 格式化返回结果
## API 配置
需要在环境变量中设置天气 API 密钥：
export WEATHER_API_KEY="your_api_key"
## 输出格式
天气信息以结构化格式返回：
{
"city": "北京",
"temperature": "25°C",
"condition": "晴",
"humidity": "45%",
"forecast": [...]
}上述 SKILL.md 文件展示了技能定义的标准格式。YAML 前置元数据中的 name 字段定义技能的唯一标识符，description 字段描述技能的用途和触发条件，这是 AI Agent 决定是否调用该技能的关键依据。metadata 部分声明了技能的依赖项，包括必需的二进制工具和环境变量，以及自动安装脚本。Markdown 正文部分则详细说明了技能的功能、使用方法和输出格式，为 AI Agent 提供执行指令。
3.3 元数据字段详解
| 字段 | 必需 | 说明 | 示例 |
|---|---|---|---|
name |
✅ | 技能唯一标识符 | weather-forecast |
description |
✅ | 技能描述和触发条件 | 获取天气信息... |
metadata.openclaw.requires |
❌ | 运行时依赖 | bins: ["curl"] |
metadata.openclaw.install |
❌ | 自动安装配置 | pip install requests |
version |
❌ | 技能版本号 | 1.2.0 |
author |
❌ | 作者信息 | 墨离 <moli@openclaw.ai> |
3.4 技能包大小限制
为确保传输效率和加载速度，技能包应遵循以下限制：
| 资源类型 | 建议上限 | 说明 |
|---|---|---|
| SKILL.md | 500 行 | 主文件保持精简 |
| 单个脚本 | 1000 行 | 复杂逻辑拆分到多个文件 |
| 总包大小 | 10 MB | 不含大型模型文件 |
| 图片资源 | 500 KB/张 | 使用压缩格式 |
4. 版本管理策略
4.1 语义化版本控制
ClawHub 强制要求使用语义化版本（Semantic Versioning），版本号格式为 MAJOR.MINOR.PATCH：
版本号 1.2.3
MAJOR 主版本
MINOR 次版本
PATCH 补丁版本
不兼容的 API 变更
向后兼容的功能新增
向后兼容的问题修复
4.2 版本更新规则
| 变更类型 | 版本变更 | 示例 | 说明 |
|---|---|---|---|
| 破坏性变更 | MAJOR +1 | 1.0.0 → 2.0.0 | API 不兼容更新 |
| 新增功能 | MINOR +1 | 1.0.0 → 1.1.0 | 向后兼容的新特性 |
| Bug 修复 | PATCH +1 | 1.0.0 → 1.0.1 | 向后兼容的修复 |
4.3 变更日志规范
每个版本发布时应附带清晰的变更日志：
markdown
## [1.2.0] - 2026-03-19
### Added
- 新增多城市天气对比功能
- 支持天气预警推送
### Changed
- 优化 API 调用性能，响应时间降低 30%
- 更新城市名称解析逻辑
### Fixed
- 修复时区转换错误问题
- 修复特殊字符编码问题
### Deprecated
- `getWeather()` 方法将在 2.0 版本移除
- 请使用 `fetchWeatherData()` 替代4.4 版本发布流程
ClawHub Registry ClawHub CLI 本地环境 开发者 ClawHub Registry ClawHub CLI 本地环境 开发者 完成代码开发 更新版本号 编写变更日志 clawhub publish 验证技能包 上传技能包 版本号检查 安全扫描 发布成功 发布确认
5. 发布流程详解
5.1 发布前准备
在发布技能之前，需要完成以下准备工作：
5.1.1 注册 ClawHub 账号
bash
# 方式一：交互式登录
clawhub login
# 方式二：使用 API Token
export CLAWHUB_TOKEN="your_api_token"登录成功后，可以验证身份：
bash
clawhub whoami
# 输出：Logged in as moli (moli@openclaw.ai)5.1.2 验证技能结构
使用内置验证工具检查技能包是否符合规范：
bash
# 验证技能目录
clawhub validate ./my-skill
# 输出示例
✅ SKILL.md 格式正确
✅ 元数据完整
✅ 依赖声明有效
⚠️ 建议：添加 README.md 文件5.2 发布命令详解
ClawHub CLI 的 publish 命令支持多种参数：
bash
clawhub publish ./my-skill \
--slug my-skill \
--name "My Skill" \
--version 1.2.0 \
--changelog "新增天气对比功能"| 参数 | 必需 | 说明 |
|---|---|---|
--slug |
✅ | 技能 URL 标识符 |
--name |
✅ | 技能显示名称 |
--version |
✅ | 版本号 |
--changelog |
❌ | 变更日志 |
--registry |
❌ | 自定义仓库地址 |
--dry-run |
❌ | 模拟发布（测试用） |
5.3 完整发布示例
以下是一个完整的技能发布流程示例：
bash
#!/bin/bash
# publish-skill.sh - 技能发布脚本
set -e
# 定义技能信息
SKILL_DIR="./weather-forecast"
SKILL_SLUG="weather-forecast"
SKILL_NAME="天气预报技能"
SKILL_VERSION="1.2.0"
CHANGELOG="新增多城市对比功能，优化API调用性能"
# 步骤1：验证登录状态
echo "🔐 检查登录状态..."
if ! clawhub whoami &> /dev/null; then
echo "请先登录: clawhub login"
exit 1
fi
# 步骤2：验证技能结构
echo "🔍 验证技能结构..."
clawhub validate "$SKILL_DIR"
# 步骤3：运行测试（如果有）
echo "🧪 运行测试..."
if [ -d "$SKILL_DIR/tests" ]; then
cd "$SKILL_DIR" && npm test && cd ..
fi
# 步骤4：模拟发布
echo "📦 模拟发布..."
clawhub publish "$SKILL_DIR" \
--slug "$SKILL_SLUG" \
--name "$SKILL_NAME" \
--version "$SKILL_VERSION" \
--changelog "$CHANGELOG" \
--dry-run
# 步骤5：确认发布
read -p "确认发布? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
echo "🚀 正式发布..."
clawhub publish "$SKILL_DIR" \
--slug "$SKILL_SLUG" \
--name "$SKILL_NAME" \
--version "$SKILL_VERSION" \
--changelog "$CHANGELOG"
echo "✅ 发布成功!"
fi上述脚本展示了技能发布的完整自动化流程。首先检查用户登录状态，确保有发布权限；然后验证技能目录结构是否符合规范；接着运行测试用例确保代码质量；使用 --dry-run 参数进行模拟发布，预览发布结果；最后在用户确认后执行正式发布。这种分步骤、可验证的发布流程可以有效避免发布错误，保证技能质量。
5.4 发布后验证
发布成功后，可以通过以下方式验证：
bash
# 搜索刚发布的技能
clawhub search "weather-forecast"
# 查看技能详情
clawhub info weather-forecast
# 尝试安装
clawhub install weather-forecast --version 1.2.05.5 发布常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 版本号已存在 | 重复发布相同版本 | 更新版本号后重试 |
| 认证失败 | Token 过期或无效 | 重新执行 clawhub login |
| 技能包过大 | 超过大小限制 | 压缩资源或移除不必要文件 |
| 元数据缺失 | 必填字段为空 | 补充 SKILL.md 元数据 |
6. 技能文档编写
6.1 文档结构规范
一份高质量的技能文档应包含以下部分：
技能文档
概述
功能简介
使用场景
快速开始
安装指南
环境要求
安装步骤
配置方法
使用说明
基本用法
参数说明
示例代码
进阶主题
自定义配置
最佳实践
性能优化
故障排除
常见问题
错误代码
获取帮助
6.2 README.md 编写指南
README.md 是技能的门面，应简洁明了地展示技能价值：
markdown
# 天气预报技能 🌤️
[](https://clawhub.com/skill/weather-forecast)
[](https://clawhub.com/skill/weather-forecast)
[](LICENSE)
一键获取全球城市天气信息，支持实时天气和多日预报。
## ✨ 特性
- 🌍 支持全球 200,000+ 城市
- ⚡ 毫秒级响应速度
- 📊 详细的气象数据
- 🔔 天气预警推送
## 📦 安装
clawhub install weather-forecast
## 🚀 快速开始
# 查询北京天气
"北京今天天气怎么样？"
# 获取三日预报
"未来三天上海的天气如何？"
## ⚙️ 配置
设置环境变量：
export WEATHER_API_KEY="your_api_key"
## 📖 文档
- [完整文档](./docs/README.md)
- [API 参考](./docs/api.md)
- [示例代码](./examples/)
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 许可证
MIT License6.3 代码注释规范
技能中的脚本代码应包含清晰的注释：
python
#!/usr/bin/env python3
"""
天气数据获取模块
本模块负责从天气 API 获取数据并进行解析处理。
支持实时天气查询和多日天气预报功能。
依赖:
- requests: HTTP 请求库
- python-dateutil: 日期处理库
作者: 墨离
版本: 1.2.0
"""
import os
import requests
from datetime import datetime
from typing import Dict, List, Optional
# API 配置常量
API_BASE_URL = "https://api.weatherapi.com/v1"
DEFAULT_TIMEOUT = 10 # 请求超时时间（秒）
MAX_RETRIES = 3 # 最大重试次数
class WeatherClient:
"""
天气 API 客户端
用于与天气 API 交互，获取天气数据。
Attributes:
api_key (str): API 密钥
base_url (str): API 基础 URL
timeout (int): 请求超时时间
Example:
>>> client = WeatherClient("your_api_key")
>>> weather = client.get_current("Beijing")
>>> print(weather["temp_c"])
25
"""
def __init__(self, api_key: str, base_url: str = API_BASE_URL):
"""
初始化天气客户端
Args:
api_key: 天气 API 密钥
base_url: API 基础 URL（可选）
Raises:
ValueError: 当 api_key 为空时抛出
"""
if not api_key:
raise ValueError("API 密钥不能为空")
self.api_key = api_key
self.base_url = base_url
self.timeout = DEFAULT_TIMEOUT
def get_current(self, city: str) -> Dict:
"""
获取指定城市的实时天气
Args:
city: 城市名称，支持中文和英文
Returns:
包含天气信息的字典，结构如下：
{
"city": "北京",
"temp_c": 25,
"condition": "晴",
"humidity": 45,
"wind_kph": 12
}
Raises:
requests.RequestException: 网络请求失败
ValueError: 城市不存在
"""
endpoint = f"{self.base_url}/current.json"
params = {
"key": self.api_key,
"q": city,
"lang": "zh"
}
response = requests.get(
endpoint,
params=params,
timeout=self.timeout
)
response.raise_for_status()
data = response.json()
return self._parse_current_weather(data)
def _parse_current_weather(self, data: Dict) -> Dict:
"""
解析天气 API 返回的原始数据
Args:
data: API 返回的原始 JSON 数据
Returns:
标准化的天气数据字典
"""
return {
"city": data["location"]["name"],
"temp_c": data["current"]["temp_c"],
"condition": data["current"]["condition"]["text"],
"humidity": data["current"]["humidity"],
"wind_kph": data["current"]["wind_kph"],
"last_updated": data["current"]["last_updated"]
}上述 Python 代码展示了天气数据获取模块的完整实现。代码遵循 Google 风格的文档字符串规范，每个类和方法都包含详细的说明，包括参数类型、返回值结构和可能抛出的异常。模块级别的文档字符串说明了模块的整体功能和依赖项。类型注解（Type Hints）的使用让代码更加清晰，也便于 IDE 进行类型检查。这种规范的代码注释方式不仅有助于其他开发者理解和使用代码，也便于 AI Agent 正确调用技能功能。
6.4 示例代码编写
提供丰富的示例代码可以大大降低使用门槛：
markdown
## 使用示例
### 示例 1：查询实时天气
from weather_forecast import WeatherClient
# 初始化客户端
client = WeatherClient(api_key=os.environ["WEATHER_API_KEY"])
# 查询天气
weather = client.get_current("北京")
print(f"北京当前温度：{weather['temp_c']}°C")
### 示例 2：获取天气预报
# 获取三天预报
forecast = client.get_forecast("上海", days=3)
for day in forecast:
print(f"{day['date']}: {day['condition']}, {day['temp_c']}°C")
### 示例 3：多城市对比
cities = ["北京", "上海", "广州"]
comparison = client.compare_cities(cities)
for city, weather in comparison.items():
print(f"{city}: {weather['temp_c']}°C, {weather['condition']}")7. 社区贡献指南
7.1 贡献方式
ClawHub 社区欢迎多种形式的贡献：
| 贡献类型 | 说明 | 如何开始 |
|---|---|---|
| 🐛 Bug 报告 | 发现并报告问题 | 提交 Issue |
| 💡 功能建议 | 提出新功能想法 | 提交 Feature Request |
| 📝 文档改进 | 完善文档内容 | Fork → Edit → PR |
| 🔧 代码贡献 | 修复 Bug 或添加功能 | Fork → Branch → PR |
| 🌍 翻译 | 多语言支持 | 加入翻译团队 |
7.2 贡献流程
是
否
否
是
否
是
发现技能问题/有改进想法
是否已有相关 Issue?
在现有 Issue 下评论
创建新 Issue
Fork 技能仓库
创建功能分支
编写代码/文档
运行测试
测试通过?
提交 Pull Request
代码审查
审查通过?
根据反馈修改
合并到主分支
发布新版本
7.3 Pull Request 规范
提交 PR 时应遵循以下规范：
markdown
## PR 描述
### 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 性能优化
- [ ] 代码重构
### 关联 Issue
Fixes #123
### 变更说明
简要描述本次变更的内容和原因。
### 测试情况
- [ ] 已添加单元测试
- [ ] 已更新文档
- [ ] 本地测试通过
### 截图（如适用）
添加相关截图说明变更效果。7.4 代码审查标准
ClawHub 社区对代码审查有以下标准：
| 审查维度 | 检查项 | 权重 |
|---|---|---|
| 功能正确性 | 代码是否实现预期功能 | ⭐⭐⭐⭐⭐ |
| 代码质量 | 可读性、可维护性、代码风格 | ⭐⭐⭐⭐ |
| 测试覆盖 | 单元测试、集成测试是否充分 | ⭐⭐⭐⭐ |
| 文档完整 | README、API 文档是否更新 | ⭐⭐⭐ |
| 安全性 | 是否存在安全风险 | ⭐⭐⭐⭐⭐ |
7.5 社区行为准则
为确保社区健康发展，所有贡献者应遵守以下准则：
✅ 应该做的：
- 尊重不同观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心
❌ 不应该做的：
- 使用性化的语言或图像
- 发表侮辱性/贬损性评论
- 进行人身攻击或政治攻击
- 未经许可发布他人的私人信息
8. 最佳实践
8.1 技能设计原则
设计高质量技能应遵循以下原则：
| 原则 | 说明 | 实践方法 |
|---|---|---|
| 单一职责 | 每个技能专注一个领域 | 拆分复杂功能为多个技能 |
| 渐进增强 | 核心功能优先，扩展功能可选 | 使用可选配置项 |
| 防御性编程 | 预期错误并优雅处理 | 完善错误处理和日志 |
| 可测试性 | 代码易于测试 | 依赖注入、模块化设计 |
8.2 性能优化建议
性能优化
减少 API 调用
缓存策略
异步处理
资源压缩
批量请求
按需加载
内存缓存
持久化缓存
非阻塞操作
并发执行
图片压缩
代码压缩
8.3 安全性考虑
发布技能前，务必进行安全检查：
bash
# 检查敏感信息泄露
grep -r "password\|secret\|token\|api_key" ./my-skill
# 检查依赖漏洞
npm audit
pip-audit
# 运行安全扫描
clawhub scan ./my-skill安全检查清单：
- 不硬编码敏感信息（API Key、密码等）
- 使用环境变量存储敏感配置
- 验证所有用户输入
- 限制文件系统访问范围
- 使用 HTTPS 进行网络请求
- 不执行未经校验的代码
8.4 版本兼容性维护
维护技能的向后兼容性：
python
# 推荐做法：保留旧接口，添加新接口
# 旧版本接口（标记为废弃）
def getWeather(city: str) -> dict:
"""
获取天气信息（已废弃，请使用 get_current_weather）
Deprecated: 将在 2.0 版本移除
"""
import warnings
warnings.warn(
"getWeather 已废弃，请使用 get_current_weather",
DeprecationWarning,
stacklevel=2
)
return get_current_weather(city)
# 新版本接口
def get_current_weather(city: str, units: str = "metric") -> dict:
"""
获取当前天气信息
Args:
city: 城市名称
units: 单位制（metric/imperial）
"""
# 新实现
pass8.5 持续集成建议
为技能项目配置 CI/CD 流程：
yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run tests
run: npm test
- name: Validate skill
run: npx clawhub validate .
- name: Security scan
run: npm audit8.6 发布节奏建议
| 发布类型 | 频率 | 说明 |
|---|---|---|
| PATCH 版本 | 按需 | Bug 修复，随时发布 |
| MINOR 版本 | 2-4 周 | 新功能，充分测试后发布 |
| MAJOR 版本 | 谨慎 | 破坏性变更，提前公告 |
9. 实战案例：发布一个完整技能
9.1 案例背景
假设我们要开发并发布一个「GitHub 仓库分析」技能，帮助用户快速了解 GitHub 仓库的基本信息。
9.2 技能结构
github-analyzer/
├── SKILL.md
├── README.md
├── scripts/
│ └── analyzer.py
├── references/
│ └── api-reference.md
└── tests/
└── test_analyzer.py9.3 核心代码
python
#!/usr/bin/env python3
"""
GitHub 仓库分析器
分析 GitHub 仓库的基本信息，包括星标数、贡献者、
最近活动等指标。
作者: 墨离
版本: 1.0.0
"""
import requests
from typing import Dict, List, Optional
from dataclasses import dataclass
from datetime import datetime, timedelta
@dataclass
class RepoStats:
"""仓库统计数据类"""
name: str
stars: int
forks: int
watchers: int
open_issues: int
language: str
created_at: datetime
updated_at: datetime
contributors_count: int
class GitHubAnalyzer:
"""GitHub 仓库分析器"""
API_BASE = "https://api.github.com"
def __init__(self, token: Optional[str] = None):
"""
初始化分析器
Args:
token: GitHub Personal Access Token（可选，提高速率限制）
"""
self.session = requests.Session()
if token:
self.session.headers["Authorization"] = f"token {token}"
self.session.headers["Accept"] = "application/vnd.github.v3+json"
def analyze(self, owner: str, repo: str) -> RepoStats:
"""
分析指定仓库
Args:
owner: 仓库所有者
repo: 仓库名称
Returns:
RepoStats 对象包含仓库统计信息
Raises:
requests.HTTPError: API 请求失败
ValueError: 仓库不存在
"""
# 获取仓库基本信息
repo_url = f"{self.API_BASE}/repos/{owner}/{repo}"
response = self.session.get(repo_url, timeout=10)
response.raise_for_status()
repo_data = response.json()
# 获取贡献者数量
contributors_url = f"{repo_url}/contributors"
contributors_response = self.session.get(
contributors_url,
params={"per_page": 1},
timeout=10
)
# 从 Link header 解析总数
contributors_count = self._parse_total_count(
contributors_response.headers.get("Link", "")
)
return RepoStats(
name=repo_data["full_name"],
stars=repo_data["stargazers_count"],
forks=repo_data["forks_count"],
watchers=repo_data["watchers_count"],
open_issues=repo_data["open_issues_count"],
language=repo_data["language"] or "Unknown",
created_at=datetime.fromisoformat(
repo_data["created_at"].replace("Z", "+00:00")
),
updated_at=datetime.fromisoformat(
repo_data["updated_at"].replace("Z", "+00:00")
),
contributors_count=contributors_count
)
def _parse_total_count(self, link_header: str) -> int:
"""解析 Link header 获取总数"""
if not link_header:
return 0
# 简化实现，实际应解析 Link header
return 0
def generate_report(self, stats: RepoStats) -> str:
"""
生成分析报告
Args:
stats: 仓库统计数据
Returns:
Markdown 格式的报告字符串
"""
days_since_update = (
datetime.now(stats.updated_at.tzinfo) - stats.updated_at
).days
report = f"""# GitHub 仓库分析报告
## 基本信息
| 指标 | 数值 |
|------|------|
| 仓库名称 | {stats.name} |
| 主要语言 | {stats.language} |
| ⭐ Stars | {stats.stars:,} |
| 🍴 Forks | {stats.forks:,} |
| 👀 Watchers | {stats.watchers:,} |
| 🐛 Open Issues | {stats.open_issues:,} |
| 👥 Contributors | {stats.contributors_count:,} |
## 活跃度分析
- 创建时间：{stats.created_at.strftime('%Y-%m-%d')}
- 最后更新：{stats.updated_at.strftime('%Y-%m-%d')}
- 距今天数：{days_since_update} 天
## 健康度评估
{self._assess_health(stats)}
---
*报告生成时间：{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*
"""
return report
def _assess_health(self, stats: RepoStats) -> str:
"""评估仓库健康度"""
days_since_update = (
datetime.now(stats.updated_at.tzinfo) - stats.updated_at
).days
if days_since_update < 30:
health = "🟢 活跃"
elif days_since_update < 180:
health = "🟡 一般"
else:
health = "🔴 不活跃"
return f"健康状态：{health}（基于最近更新时间判断）"上述代码实现了一个完整的 GitHub 仓库分析器。代码采用面向对象设计，使用 dataclass 定义数据结构，使代码更加清晰。GitHubAnalyzer 类封装了与 GitHub API 的交互逻辑，包括仓库信息获取和贡献者统计。generate_report 方法生成 Markdown 格式的分析报告，便于在聊天应用中展示。错误处理方面，代码会在 API 请求失败时抛出异常，让调用方能够捕获和处理错误。
9.4 发布过程
bash
# 1. 验证技能结构
clawhub validate ./github-analyzer
# 2. 运行测试
cd github-analyzer && python -m pytest tests/
# 3. 模拟发布
clawhub publish ./github-analyzer \
--slug github-analyzer \
--name "GitHub 仓库分析器" \
--version 1.0.0 \
--changelog "首次发布" \
--dry-run
# 4. 正式发布
clawhub publish ./github-analyzer \
--slug github-analyzer \
--name "GitHub 仓库分析器" \
--version 1.0.0 \
--changelog "首次发布：支持仓库基本信息分析、活跃度评估、健康度报告生成"9.5 发布后维护
bash
# 查看下载统计
clawhub stats github-analyzer
# 查看用户反馈
clawhub issues github-analyzer
# 发布更新版本
clawhub publish ./github-analyzer \
--slug github-analyzer \
--name "GitHub 仓库分析器" \
--version 1.1.0 \
--changelog "新增：支持私有仓库分析（需配置 Token）"10. 总结
本文系统性地介绍了 OpenClaw 技能发布与共享的完整流程，从 ClawHub 技能市场的架构设计，到技能打包规范、版本管理策略、发布流程详解，再到技能文档编写和社区贡献指南，为开发者提供了一份详尽的实践指南。
核心要点总结如下：
1. ClawHub 技能市场：作为 OpenClaw 官方的技能分发平台，ClawHub 提供了标准化的技能发现、安装和发布渠道，CLI 工具让整个流程可以在命令行中完成。
2. 技能打包规范：遵循标准的目录结构和 SKILL.md 格式，确保技能的可发现性和可维护性。元数据的准确填写是技能正确触发的关键。
3. 版本管理策略：采用语义化版本控制，通过变更日志记录每次更新的内容，让用户了解版本差异并做出升级决策。
4. 发布流程：从登录认证、技能验证、模拟发布到正式发布，分步骤的流程设计确保发布质量和可追溯性。
5. 文档编写：高质量的文档是技能成功的关键，README.md 应简洁展示技能价值，代码注释应清晰说明功能和用法。
6. 社区贡献：开放的贡献流程和明确的审查标准，让社区成员能够参与技能的改进和完善，形成良性循环。
7. 最佳实践：遵循单一职责原则、注重性能优化、确保安全性、维护版本兼容性，是开发高质量技能的关键。
通过本文的学习，读者应该能够独立完成一个技能的开发、打包、发布和维护全流程。更重要的是，理解了技能共享的价值------当一个技能被社区广泛使用和改进时，它才能发挥最大的价值。期待在 ClawHub 上看到更多优秀的技能贡献！