Merge pull request #72 from iflytek/fix/global-public-download-anon

Allow anonymous downloads for global public skills

Author: wowo-zZ

README.md

@@ -302,22 +302,26 @@ Run it against a local backend:
 
 SkillHub works as a skill registry backend for several agent platforms. Point any of the clients below at your SkillHub instance to publish, discover, and install skills.
 
-### [openclaw](https://github.com/openclaw/openclaw)
+### [OpenClaw](https://github.com/openclaw/openclaw)
 
-[openclaw](https://github.com/openclaw/openclaw) is an open-source agent skill CLI. Configure it to use your SkillHub endpoint as the registry:
+[OpenClaw](https://github.com/openclaw/openclaw) is an open-source agent skill CLI. Configure it to use your SkillHub endpoint as the registry:
 
 ```bash
-# Log in to your SkillHub instance
-openclaw login --registry https://<your-skillhub-host>
-
-# Publish a skill
-openclaw push <skill-package>
+# Configure registry URL
+export CLAWHUB_REGISTRY_URL=https://skillhub.your-company.com
+export CLAWHUB_API_TOKEN=YOUR_API_TOKEN
 
 # Search and install skills
-openclaw search <keyword>
-openclaw install <namespace>/<skill>
+npx clawhub search email
+npx clawhub install my-skill
+npx clawhub install my-namespace--my-skill
+
+# Publish a skill
+npx clawhub publish ./my-skill
 ```
 
+📖 **[Complete OpenClaw Integration Guide →](./docs/openclaw-integration.md)**
+
 ### [AstronClaw](https://agent.xfyun.cn/astron-claw)
 
 [AstronClaw](https://agent.xfyun.cn/astron-claw) is the skill marketplace provided by iFlytek's Astron platform. You can connect it to a self-hosted SkillHub registry to manage and distribute private skills within your organization, or browse publicly shared skills on the Astron platform.

README_zh.md

@@ -255,6 +255,26 @@ SkillHub 采用清晰的分层架构：
 
 SkillHub 设计为与各种智能体平台和框架无缝集成。
 
+### [OpenClaw](https://github.com/openclaw/openclaw)
+
+[OpenClaw](https://github.com/openclaw/openclaw) 是开源的智能体技能 CLI 工具。配置它使用您的 SkillHub 端点作为注册中心：
+
+```bash
+# 配置注册中心地址
+export CLAWHUB_REGISTRY_URL=https://skillhub.your-company.com
+export CLAWHUB_API_TOKEN=YOUR_API_TOKEN
+
+# 搜索和安装技能
+npx clawhub search email
+npx clawhub install my-skill
+npx clawhub install my-namespace--my-skill
+
+# 发布技能
+npx clawhub publish ./my-skill
+```
+
+📖 **[完整 OpenClaw 集成指南 →](./docs/openclaw-integration.md)**
+
 ### [AstronClaw](https://agent.xfyun.cn/astron-claw)
 
 [AstronClaw](https://agent.xfyun.cn/astron-claw) 是科大讯飞星火平台提供的技能市场。您可以将其连接到自托管的 SkillHub 注册中心，在组织内管理和分发私有技能，或在星火平台上浏览公开共享的技能。

docs/openclaw-integration-en.md

@@ -0,0 +1,307 @@
+# OpenClaw Integration Guide
+
+This document explains how to configure OpenClaw CLI to connect to a SkillHub private registry for publishing, searching, and downloading skills.
+
+## Overview
+
+SkillHub provides a ClawHub-compatible API layer, allowing OpenClaw CLI to seamlessly integrate with private registries. With simple configuration, you can:
+
+- 🔍 Search for private skills within your organization
+- 📥 Download and install skill packages
+- 📤 Publish new skills to the private registry
+- ⭐ Star and rate skills
+
+## Quick Start
+
+### 1. Configure Registry URL
+
+Set the SkillHub registry address in your OpenClaw configuration:
+
+```bash
+# Via environment variable
+export CLAWHUB_REGISTRY_URL=https://skillhub.your-company.com
+```
+
+### 2. Authentication (Optional)
+
+For **global namespace (@global) PUBLIC skills**, no login is required to download. Authentication is required for:
+
+- Team namespace skills (regardless of visibility)
+- NAMESPACE_ONLY or PRIVATE skills
+- Write operations like publishing, starring, etc.
+
+```bash
+# Using API Token
+export CLAWHUB_API_TOKEN=YOUR_API_TOKEN
+```
+
+#### Obtaining an API Token
+
+1. Log in to SkillHub Web UI
+2. Navigate to **Settings → API Tokens**
+3. Click **Create New Token**
+4. Set token name and permissions
+5. Copy the generated token
+
+### 3. Search Skills
+
+```bash
+# Search for skills
+npx clawhub search email
+
+# View skill details
+npx clawhub info my-skill
+```
+
+### 4. Install Skills
+
+```bash
+# Install latest version
+npx clawhub install my-skill
+
+# Install specific version
+npx clawhub install my-skill@1.2.0
+
+# Install skill from team namespace
+npx clawhub install my-namespace--my-skill
+```
+
+### 5. Publish Skills
+
+```bash
+# Publish a skill (requires appropriate permissions)
+npx clawhub publish ./my-skill
+```
+
+## API Endpoints
+
+SkillHub compatibility layer provides the following endpoints:
+
+| Endpoint | Method | Description | Auth Required |
+|----------|--------|-------------|---------------|
+| `/api/v1/whoami` | GET | Get current user info | Yes |
+| `/api/v1/search` | GET | Search skills | Optional |
+| `/api/v1/resolve` | GET | Resolve skill version | Optional |
+| `/api/v1/download/{slug}` | GET | Download skill (redirect) | Optional* |
+| `/api/v1/download` | GET | Download skill (query params) | Optional* |
+| `/api/v1/skills/{slug}` | GET | Get skill details | Optional |
+| `/api/v1/skills/{slug}/star` | POST | Star a skill | Yes |
+| `/api/v1/skills/{slug}/unstar` | DELETE | Unstar a skill | Yes |
+| `/api/v1/publish` | POST | Publish a skill | Yes |
+
+\* Download endpoint authentication requirements:
+- **Global namespace (@global) PUBLIC skills**: No authentication required
+- **All team namespace skills**: Authentication required
+- **NAMESPACE_ONLY and PRIVATE skills**: Authentication required
+
+## Skill Visibility Levels
+
+SkillHub supports three visibility levels with the following download permission rules:
+
+### PUBLIC
+- ✅ Anyone can search and view
+- ✅ **Global namespace (@global)**: No login required to download
+- 🔒 **Team namespaces**: Authentication required to download
+- 📍 Suitable for organization-wide, publicly shareable skills
+
+### NAMESPACE_ONLY
+- ✅ Namespace members can search and view
+- 🔒 Login required and must be namespace member to download
+- 📍 Suitable for team-internal skills
+
+### PRIVATE
+- ✅ Only owner can view
+- 🔒 Login required and must be owner to download
+- 📍 Suitable for skills under personal development
+
+**Important Notes**:
+- Global namespace (`@global`) PUBLIC skills support anonymous downloads for wide distribution within the organization
+- All team namespace skills (including PUBLIC) require authentication to ensure team boundary security
+
+## Canonical Slug Mapping
+
+SkillHub internally uses `@{namespace}/{skill}` format, but the compatibility layer automatically converts to ClawHub-style canonical slugs:
+
+| SkillHub Internal | Canonical Slug | Description |
+|-------------------|----------------|-------------|
+| `@global/my-skill` | `my-skill` | Global namespace skill |
+| `@my-team/my-skill` | `my-team--my-skill` | Team namespace skill |
+
+OpenClaw CLI uses canonical slug format, and SkillHub handles the conversion automatically.
+
+## Configuration Examples
+
+### ClawHub CLI Environment Variables
+
+ClawHub CLI is configured via environment variables:
+
+```bash
+# Registry configuration
+export CLAWHUB_REGISTRY_URL=https://skillhub.your-company.com
+export CLAWHUB_API_TOKEN=sk_your_api_token_here
+```
+
+### Environment Variables
+
+```bash
+# Registry configuration
+export CLAWHUB_REGISTRY_URL=https://skillhub.your-company.com
+export CLAWHUB_API_TOKEN=sk_your_api_token_here
+
+# Optional: Skip SSL verification (development only)
+export CLAWHUB_SKIP_SSL_VERIFY=false
+```
+
+## FAQ
+
+### Q: How do I switch back to public ClawHub?
+
+```bash
+# Unset custom registry
+unset CLAWHUB_REGISTRY_URL
+
+# ClawHub CLI will use the default public registry
+```
+
+### Q: Getting 403 Forbidden when downloading?
+
+Possible causes:
+1. Skill belongs to a team namespace, authentication required
+2. Skill is NAMESPACE_ONLY or PRIVATE, authentication required
+3. You're not a member of the namespace
+4. API Token has expired
+
+Solution:
+```bash
+# Set new token
+export CLAWHUB_API_TOKEN=YOUR_NEW_TOKEN
+
+# Test connection
+curl https://skillhub.your-company.com/api/v1/whoami \
+  -H "Authorization: Bearer $CLAWHUB_API_TOKEN"
+```
+
+**Tip**: Global namespace (@global) PUBLIC skills can be downloaded anonymously without authentication.
+
+### Q: How do I see all skills I have access to?
+
+```bash
+# Search all skills (filtered by permissions)
+npx clawhub search ""
+```
+
+### Q: Permission denied when publishing?
+
+- Publishing to global namespace (`@global`) requires `SUPER_ADMIN` permission
+- Publishing to team namespace requires OWNER or ADMIN role in that namespace
+- Contact your administrator for appropriate permissions
+
+### Q: Which OpenClaw versions are supported?
+
+SkillHub compatibility layer is designed to work with tools using ClawHub CLI. ClawHub CLI is distributed via npm:
+
+```bash
+# Install ClawHub CLI
+npm install -g clawhub
+
+# Or use npx directly
+npx clawhub install my-skill
+```
+
+If you encounter compatibility issues, please file an issue.
+
+## API Response Formats
+
+### Search Response Example
+
+```json
+{
+  "results": [
+    {
+      "slug": "my-team--email-sender",
+      "name": "Email Sender",
+      "description": "Send emails via SMTP",
+      "author": {
+        "handle": "user123",
+        "displayName": "John Doe"
+      },
+      "version": "1.2.0",
+      "downloadCount": 150,
+      "starCount": 25,
+      "createdAt": "2026-01-15T10:00:00Z",
+      "updatedAt": "2026-03-10T14:30:00Z"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "limit": 20
+}
+```
+
+### Version Resolution Response Example
+
+```json
+{
+  "slug": "my-skill",
+  "version": "1.2.0",
+  "downloadUrl": "/api/v1/skills/global/my-skill/versions/1.2.0/download"
+}
+```
+
+### Publish Response Example
+
+```json
+{
+  "id": "12345",
+  "version": {
+    "id": "67890"
+  }
+}
+```
+
+## Security Recommendations
+
+1. **Use HTTPS**: Always use HTTPS in production
+2. **Token Management**:
+   - Rotate API tokens regularly
+   - Never hardcode tokens in code
+   - Use environment variables or secret management tools
+3. **Least Privilege**: Assign minimum required permissions to tokens
+4. **Audit Logs**: Regularly review SkillHub audit logs
+
+## Troubleshooting
+
+### Enable Debug Logging
+
+```bash
+# View detailed request logs
+DEBUG=clawhub:* npx clawhub search my-skill
+
+# Or use verbose mode
+npx clawhub --verbose install my-skill
+```
+
+### Test Connection
+
+```bash
+# Test registry connection
+curl https://skillhub.your-company.com/api/v1/whoami \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# Test search
+curl "https://skillhub.your-company.com/api/v1/search?q=test"
+```
+
+## Further Reading
+
+- [SkillHub API Design](./06-api-design.md)
+- [Skill Protocol Specification](./07-skill-protocol.md)
+- [Authentication & Authorization](./03-authentication-design.md)
+- [Deployment Guide](./09-deployment.md)
+
+## Support
+
+For questions or suggestions:
+- 📖 Full Documentation: https://zread.ai/iflytek/skillhub
+- 💬 GitHub Discussions: https://github.com/iflytek/skillhub/discussions
+- 🐛 Submit Issues: https://github.com/iflytek/skillhub/issues