feat(skills): add registry doctor diagnostics and docs

README.md

@@ -93,6 +93,36 @@ flynn completion zsh --install     # Install zsh completions to ~/.zshrc
 flynn completion fish --install    # Install fish completions to config
 ```
 
+## Skills Registry
+
+Flynn supports registry-backed skill discovery and install-by-id.
+
+Registry source configuration:
+
+```yaml
+skills:
+  registry_source: ~/.config/flynn/skills-registry.json
+```
+
+You can also set `FLYNN_SKILLS_REGISTRY_SOURCE` instead of `skills.registry_source`.
+
+Common commands:
+
+```bash
+# Discover registry entries
+flynn skills registry list
+flynn skills registry list --search todo --publisher acme --json
+flynn skills registry show todoist
+
+# Install by registry id
+flynn skills install --registry-id todoist
+
+# For non-local registry sources (git/archive), explicit confirmation is required
+flynn skills install --registry-id todoist --confirm
+```
+
+Registry metadata (`publisher`, `homepage`, `sha256`) is treated as declared and unverified. Skill scanner checks still run before installation succeeds.
+
 ## Configuration
 
 Config location: `~/.config/flynn/config.yaml` (or set `FLYNN_CONFIG`)
@@ -849,7 +879,7 @@ See `docs/deployment/NIX.md` for the flake (package + dev shell + optional NixOS
 
 ## Doctor Diagnostics
 
-`flynn doctor` runs 10 health checks to validate your setup:
+`flynn doctor` runs health checks to validate your setup:
 
 ```
 $ flynn doctor
@@ -885,6 +915,7 @@ Results: 8 passed, 0 failed, 0 warnings, 1 skipped
 | Telegram bot configured | Bot token is present and reasonable length |
 | MCP servers configured | Lists configured MCP tool servers |
 | Skills loaded | Discovers and loads skill packages |
+| Skills registry | Verifies registry source is configured and catalog is reachable/parsible |
 
 Exit code is `1` if any check fails, `0` otherwise. Checks that depend on a valid config are skipped when config is invalid.