# ClawHub Registry — Scoped Implementation Checklist

**Date:** 2026-02-16

**Parent roadmap:** `docs/plans/2026-02-15-openclaw-gap-roadmap.md`

**Goal:** Close the gap item "ClawHub / community skill registry" with a safe, incremental registry flow that supports discovery and installation without weakening current skill safety controls.

## Scope

### In scope

- Add a read-only skill registry source for discovery.
- Add CLI registry listing/details and install-by-id flow.
- Reuse existing skill safety scanner and install policy gates.
- Add docs and tests for end-to-end registry flow.

### Out of scope (this milestone)

- Arbitrary third-party repository execution without safety checks.
- Auto-update/auto-upgrade daemons for installed skills.
- Full signed-package ecosystem (can be follow-up phase).

## Phase Plan

### Phase 1: Registry Source + Types

Checklist:

- [x] Add registry types + parser module (`src/skills/registrySource.ts` or equivalent).
- [x] Support one source shape:
  - [x] local JSON file path (for deterministic tests and offline use)
  - [x] optional HTTPS URL source (fetch + timeout + parse)
- [x] Validate required fields for each skill entry:
  - [x] `id`, `name`, `version`, `source`, `summary`
  - [x] optional trust metadata (`publisher`, `homepage`, `sha256`)
- [x] Reject malformed registry entries with actionable errors.

Acceptance:

- [x] `flynn skills` internals can load a normalized registry catalog.

Tests:

- [x] Unit tests for parser/validation edge cases.

---

### Phase 2: CLI Discovery UX

Checklist:

- [x] Add `flynn skills registry list` command (table/text + `--json`).
- [x] Add `flynn skills registry show <id>` command (entry detail + source fields).
- [x] Add filtering options:
  - [x] `--search <term>`
  - [x] `--publisher <name>`
- [x] Ensure output clearly marks trust metadata as declared/unverified.

Acceptance:

- Operators can discover candidate skills without leaving Flynn tooling.

Tests:

- [x] Command tests for text + JSON output paths.

---

### Phase 3: Install by Registry ID

Checklist:

- [ ] Add `flynn skills install --registry-id <id>` resolution path.
- [ ] Support source forms:
  - [ ] git URL
  - [ ] archive URL
  - [ ] local path
- [ ] Route resolved sources through existing installer + scanner pipeline.
- [ ] Require explicit confirmation flag for non-local sources (for example `--confirm`).
- [ ] Emit audit events for registry-driven installs (id + source + outcome).

Acceptance:

- Install-by-id works and unsafe skills still fail scanner checks.

Tests:

- [ ] Installer tests for registry-id resolution and scan failures.
- [ ] CLI tests for confirmation and error paths.

---

### Phase 4: Docs + Runtime Visibility

Checklist:

- [ ] Update `README.md` skills section with registry usage.
- [ ] Update `docs/security/SAFE_PERSONAL_AGENT.md` with registry trust model.
- [ ] Add doctor diagnostics:
  - [ ] registry source reachable/parsible
  - [ ] clear warning when registry disabled/unconfigured

Acceptance:

- Operator docs explain safe usage and tradeoffs.

Tests:

- [ ] Doctor tests for registry health reporting.

## Security Guardrails

- [ ] Registry metadata is never treated as trusted code.
- [ ] Skill scanner remains mandatory before skill becomes available.
- [ ] Prompt injection and symlink/binary checks still gate registry-installed skills.
- [ ] Secrets are never accepted from registry metadata.

## Final Validation

- [ ] `pnpm typecheck`
- [ ] `pnpm test:run`
- [ ] Update `docs/plans/state.json` to `completed` with summary + test status once all phases land.