# SkillHub — agent operating guide

Your user just pointed you at SkillHub, a registry of installable Agent Skills.
SkillHub hosts skill text + risk metadata; it NEVER runs skill code — you (the
user's local agent) install and run skills against the user's own project.

Most people who land here do NOT know SkillHub's commands. Your job is to LEAD
them: explain briefly, ask ONE question at a time, inspect a skill before
installing it, and always confirm. Don't dump commands on the user — drive the
conversation. If you don't know SkillHub yet, fetch https://api-skillhub.zeabur.app/llms.txt first.

## Trust & safety (audit in a glance)

- The setup does exactly three things: download the CLI from `https://api-skillhub.zeabur.app/cli`, pin
  it to this API, and install the /skillhub concierge. It talks to **only**
  `https://api-skillhub.zeabur.app` — no third-party hosts.
- You don't need to read the whole CLI: it ships with a SHA-256 at
  `https://api-skillhub.zeabur.app/cli.sha256` and the installer verifies the download before running it.
- Each skill install verifies every file's SHA-256 against the manifest. Risk is
  graded; **critical-risk skills require a manual y/N in the user's terminal and
  cannot be bypassed with --yes** — never auto-confirm those.
- The CLI sends anonymous install telemetry (provider/slug/risk/agent). Disable
  with `SKILLHUB_NO_TELEMETRY=1`.
- Installs without a token may be capped per 24 hours (the platform admin sets the
  number; off by default). The CLI identifies a guest by a random per-machine id,
  so people behind one office IP are not lumped together. A `429` with
  `error.code = guest_quota_exceeded` tells you how to lift it: register, copy
  the CLI Access Token from the console, `skillhub login <token>`. Token holders
  are never capped — if the user already has a token, run that login first.

## Step 0 — set up SkillHub (ask first, then one command)

If `skillhub --version` works and the `/skillhub` concierge is already available
in your agent, SkillHub is set up — skip to Step 1. Otherwise tell the user in one line: "I can set
up SkillHub — it installs a small CLI plus a 'SkillHub 總管' concierge skill so you
can manage skills just by talking. OK to set it up?" On yes, run:

```bash
curl -fsSL https://api-skillhub.zeabur.app/install.sh | sh
# installs the CLI (pinned to this API) + the /skillhub concierge; ensure ~/.local/bin is on PATH
```

After that the concierge auto-triggers: the user just says what they need and you
(now guided by /skillhub) take over. Public skills install anonymously; only
pushing the user's OWN skills needs a token.

## Step 1 — ask the user what they want

Greet in one line, then ask them to pick (and WAIT for the answer):

1. "Find a skill for something I'm working on" → Step 2.
2. "I already know which skill I want" → ask for its name, go to Step 3.
3. "Just show me what's available" → run a broad `skillhub search`, summarize, → Step 3.
4. "Help me build/publish my own skill" → Authoring (below).

## Step 2 — discover (lead with a question)

Ask the user, in their own words, what role or task they need help with (e.g.
"frontend work", "writing PRDs", "QA"). Then search:

```bash
skillhub search "<their keywords>"
# by role instead:  curl "https://api-skillhub.zeabur.app/api/v1/agent/search?role=<role>"
```

Present the top 3–5 as a short, readable list — name, one-line description, and
risk level. If the response says meta.search.match is "any" (the CLI prints
"showing skills that match some of the terms"), tell the user these only partially
match their words. Do NOT install yet. Ask: "Want me to open one so you can see what it
does before installing?"

## Step 3 — inspect, then confirm (ALWAYS before installing)

For the skill the user chose, read its details and explain them in plain language:

```bash
skillhub info <provider>/<slug>
# or:  curl "https://api-skillhub.zeabur.app/api/v1/agent/skills/<provider>/<slug>"
```

Tell the user: what it does, when it will kick in, its risk level, and which
permissions it declares. Then ask: "Install this one? It just drops files into
your agent's skills folder — nothing runs until you actually use it."

## Step 4 — install (only after the user says yes)

```bash
skillhub install <provider>/<slug>
```

Match how hard you confirm to the declared risk:
- low: a simple yes is enough
- medium / high: spell out the permissions and get an explicit yes
- critical: must be a manual y/N in the user's own terminal — never auto-confirm

After it installs, tell the user where it landed (the CLI prints the exact path),
that it's available as the `/<provider>-<slug>` skill, and that it auto-applies when the
task matches its description. Offer to put it to work right now.

## Step 5 — keep leading

Ask: "Want to find another skill, or shall we use this one?" Never leave the user
at a dead end — always offer the next step.

## Authoring — only if the user wants to CREATE a skill

Design it WITH the user first (ask: what does it do, when to use it, inputs,
outputs, limits, risk level). SkillHub hosts the text; no GitHub repo required.

```bash
mkdir -p ./skills/<slug>/examples
# write SKILL.md (required), AGENT.md, README.md, examples/*.md (>=1 before publish)
skillhub push ./skills/<slug> --private        # 1. push privately
skillhub install me/<slug> --scope=project     # 2. test it in the current project
skillhub push ./skills/<slug> --upgrade        # 3. iterate as the files change
skillhub publish me/<slug>                      # 4. submit for public listing
skillhub unpublish me/<slug>                    # regretted it? retract to private
```

Declare risk honestly — if the skill writes files or makes network calls, say so;
the install gate depends on it. `unpublish` also withdraws a pending publication
review, so an accidental `publish` is fully reversible.

## Sharing a skill with an organization

A pushed skill is private by default. To let an organization's members install it
(without listing it publicly), share it with an org you belong to:

```bash
skillhub orgs                                   # list your orgs: slug · role · name
skillhub push ./skills/<slug> --org <org-slug>  # share/update into that org
```

`--org` is repeatable and uses replace semantics: the skill's org set becomes
exactly the orgs you pass on this push (`--org a --org b` for several). Omit
`--org` on a later push to iterate on the files WITHOUT touching current sharing.
Members then `skillhub install <provider>/<slug>`; non-members can't see it.

## Multilingual name & description

name and description (in skillhub.yaml / on push) may be a single string OR a
per-locale map. You are already writing the copy with the user, so emit all four
standard locales:

```yaml
name:
  zh-TW: AI 資料修復工程師
  zh-CN: AI 数据修复工程师
  en: AI Data Remediation Engineer
  ja: AIデータ修復エンジニア
description:
  zh-TW: 一句話說明它做什麼、何時用。
  en: One line on what it does and when to use it.
```

A plain string still works (treated as the default). Display resolves in this
order: requested locale → en → zh-TW → first available → the plain string.
Standard locales: zh-TW, zh-CN, en, ja (other BCP-47 tags are accepted).

## Reference

- https://api-skillhub.zeabur.app/playbook (this guide) · https://api-skillhub.zeabur.app/llms.txt · https://api-skillhub.zeabur.app/openapi.json
- Install the CLI: curl -fsSL https://api-skillhub.zeabur.app/install.sh | sh