|
| 1 | +--- |
| 2 | +name: skillhub-registry |
| 3 | +description: Use this when you need to search, inspect, install, or publish agent skills against a SkillHub registry. SkillHub is a skill registry with a ClawHub-compatible API layer, so prefer the `clawhub` CLI for registry operations instead of making raw HTTP calls. |
| 4 | +--- |
| 5 | + |
| 6 | +# SkillHub Registry |
| 7 | + |
| 8 | +Use this skill when you need to work with a SkillHub registry: search skills, inspect metadata, install a package, or publish a new version. |
| 9 | + |
| 10 | +> Important: Prefer the `clawhub` CLI for registry workflows. SkillHub exposes a ClawHub-compatible API surface and a discovery endpoint at `/.well-known/clawhub.json`, so the CLI is the safest path for auth, resolution, and download behavior. Only fall back to raw HTTP when debugging the server itself. |
| 11 | + |
| 12 | +## What SkillHub Is |
| 13 | + |
| 14 | +SkillHub is an enterprise-oriented skill registry. It stores versioned skill packages, supports namespace-based skill management, and keeps `SKILL.md` compatibility with OpenSkills-style packages. |
| 15 | + |
| 16 | +Key facts: |
| 17 | + |
| 18 | +- Internal coordinates use `@{namespace}/{skill_slug}`. |
| 19 | +- If using the clawhub CLI, the compatible format is `{namespace}--{skill_slug}`. |
| 20 | +- ClawHub-compatible clients use a `{namespace}--{skill_slug}` slug instead. |
| 21 | +- `latest` always means the latest published version, never draft or pending review. |
| 22 | +- Public skills in `@global` can be downloaded anonymously. |
| 23 | +- If no namespace is specified, it defaults to `@global`. |
| 24 | +- `{skill_slug}` can be used instead of `global--{skill_slug}` |
| 25 | +- Team namespace skills and non-public skills require authentication. |
| 26 | + |
| 27 | +## Configure The CLI |
| 28 | + |
| 29 | +Point `clawhub` at the SkillHub base URL: |
| 30 | + |
| 31 | +```bash |
| 32 | +export CLAWHUB_REGISTRY=${SKILLHUB_PUBLIC_BASE_URL} |
| 33 | +``` |
| 34 | + |
| 35 | +Alternatively, use the `--registry` parameter every time, for example: |
| 36 | + |
| 37 | +```bash |
| 38 | +npx clawhub install my-skill --registry ${SKILLHUB_PUBLIC_BASE_URL} |
| 39 | +``` |
| 40 | + |
| 41 | + |
| 42 | +If you need authenticated access, provide an API token: |
| 43 | + |
| 44 | +```bash |
| 45 | +clawhub login --token sk_your_api_token_here |
| 46 | +``` |
| 47 | + |
| 48 | +Optional local check: |
| 49 | + |
| 50 | +```bash |
| 51 | +curl ${SKILLHUB_PUBLIC_BASE_URL}/.well-known/clawhub.json |
| 52 | +``` |
| 53 | + |
| 54 | +Expected response: |
| 55 | + |
| 56 | +```json |
| 57 | +{"apiBase":"/api/v1"} |
| 58 | +``` |
| 59 | + |
| 60 | +## Coordinate Rules - IMPORTANT |
| 61 | + |
| 62 | +SkillHub has two naming forms: |
| 63 | + |
| 64 | +| SkillHub coordinate | Canonical slug for `clawhub` | |
| 65 | +|---|---| |
| 66 | +| `@global/my-skill` | `my-skill` | |
| 67 | +| `@team-name/my-skill` | `team-name--my-skill` | |
| 68 | + |
| 69 | +Rules: |
| 70 | + |
| 71 | +- `--` is the namespace separator in the compatibility layer. |
| 72 | +- If there is no `--`, the skill is treated as `@global/...`. |
| 73 | +- `latest` resolves to the latest published version only. |
| 74 | + |
| 75 | +Examples: |
| 76 | + |
| 77 | +```bash |
| 78 | +npx clawhub install my-skill |
| 79 | +npx clawhub install my-skill@1.2.0 |
| 80 | +npx clawhub install team-name--my-skill |
| 81 | +``` |
| 82 | + |
| 83 | +## Common Workflows |
| 84 | + |
| 85 | +### Search |
| 86 | + |
| 87 | +```bash |
| 88 | +npx clawhub search email |
| 89 | +``` |
| 90 | + |
| 91 | +Use an empty query when you want a broad listing: |
| 92 | + |
| 93 | +```bash |
| 94 | +npx clawhub search "" |
| 95 | +``` |
| 96 | + |
| 97 | +### Inspect A Skill |
| 98 | + |
| 99 | +```bash |
| 100 | +npx clawhub info my-skill |
| 101 | +npx clawhub info team-name--my-skill |
| 102 | +``` |
| 103 | + |
| 104 | +### Install |
| 105 | + |
| 106 | +```bash |
| 107 | +npx clawhub install my-skill |
| 108 | +npx clawhub install my-skill@1.2.0 |
| 109 | +npx clawhub install team-name--my-skill |
| 110 | +``` |
| 111 | + |
| 112 | +### Publish |
| 113 | + |
| 114 | +Prepare a skill package directory, then publish it: |
| 115 | + |
| 116 | +```bash |
| 117 | +npx clawhub publish ./my-skill |
| 118 | +``` |
| 119 | + |
| 120 | +Publishing requires authentication and sufficient permissions in the target namespace. |
| 121 | + |
| 122 | +## Authentication And Visibility |
| 123 | + |
| 124 | +Download and search permissions depend on namespace and visibility: |
| 125 | + |
| 126 | +- `@global` + `PUBLIC`: anonymous search, inspect, and download are allowed. |
| 127 | +- Team namespace + `PUBLIC`: authentication required for download. |
| 128 | +- `NAMESPACE_ONLY`: authenticated namespace members only. |
| 129 | +- `PRIVATE`: owner or explicitly authorized users only. |
| 130 | +- Publish, star, and other write operations always require authentication. |
| 131 | + |
| 132 | +If a request fails with `403`, check: |
| 133 | + |
| 134 | +- whether the skill belongs to a team namespace, |
| 135 | +- whether the skill is `NAMESPACE_ONLY` or `PRIVATE`, |
| 136 | +- whether your token is valid, |
| 137 | +- whether you have namespace publish permissions. |
| 138 | + |
| 139 | +## Skill Package Contract |
| 140 | + |
| 141 | +SkillHub expects OpenSkills-style packages with `SKILL.md` as the entry point. |
| 142 | + |
| 143 | +## Publishing Guidance |
| 144 | + |
| 145 | +Just need to follow the OpenSkills-style standards. |
0 commit comments