# 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`.

## 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. 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
```

Declare risk honestly — if the skill writes files or makes network calls, say so;
the install gate depends on 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