flynn/docs/plans/2026-02-16-clawhub-registry-checklist.md

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:

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

Acceptance:

• flynn skills internals can load a normalized registry catalog.

Tests:

• Unit tests for parser/validation edge cases.

---

Phase 2: CLI Discovery UX

Checklist:

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

Acceptance:

• Operators can discover candidate skills without leaving Flynn tooling.

Tests:

• 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.