Fix Guide
If you installed Moltbook but still see skills not found, the root cause is usually runtime resolution mismatch, not a simple download failure. This guide gives a deterministic troubleshooting path: classify the error pattern, run command-level diagnosis, apply fix matrix actions, and verify with repeatable command flows before returning to normal development.
“Skills not found” is a surface symptom, not a root diagnosis. In many cases, installation has succeeded but runtime resolution fails because one of four assumptions breaks: version mismatch, path mismatch, permission mismatch, or index/cache mismatch. Teams often waste time by repeatedly reinstalling without checking these assumptions first. A structured process is faster because it isolates the first failing layer.
In production workflows, this distinction matters. Blind retries can temporarily clear local noise while the real issue remains in CI, container paths, or access policy. The right approach is evidence-first debugging: capture one failing command, inspect the exact environment, and only then apply the targeted fix.
Use this order. First, verify toolchain context. Confirm Node version, CLI version, and active working directory are what your team expects. Second, run a read/list command in verbose mode and save output. Third, inspect path and permissions for skill directories. Fourth, clear cache only if evidence points to stale index behavior. Fifth, rerun the same failing command and compare output deltas.
# Baseline diagnostics
npx molthub@latest --version
pwd
npx molthub@latest list --verbose
# If list works but read fails, test explicit skill path
npx molthub@latest read moltbook --verboseIf output shows skill index exists but specific read fails, prioritize path normalization and ownership checks. If output shows registry lookup failures, inspect network policy, proxy settings, and auth scope. This branch logic is what prevents random retry loops.
| Pattern | Typical Signal | Likely Root Cause | First Action |
|---|---|---|---|
| Install OK, list empty | No skills returned | Wrong working directory or stale index | Run verbose list from expected repo root |
| List shows entries, read fails | Specific skill missing | Path alias mismatch or permission issue | Check path mapping and file ownership |
| Works local, fails CI | Pipeline-only failure | Missing env vars or image drift | Diff runtime config local vs CI |
| Intermittent not found | Flaky resolution | Network policy/cache invalidation race | Log full fetch path and cache keys |
| Root Cause | Fix | Verification |
|---|---|---|
| Version mismatch | Pin known-good CLI version for team and CI | Same command output across local and CI |
| Path mismatch | Normalize working dir and skill path aliases | Verbose read resolves expected file path |
| Permission mismatch | Fix file ownership and executable permissions | Read/list commands pass under target user |
| Stale index/cache | Clear cache after log capture and rebuild index | Fresh index timestamp and stable list output |
Local machine used latest CLI while CI image had an older global package. Local read command passed, CI failed with not-found. Team pinned a tested version in CI and added a version echo preflight step. Result: failure resolved and future drift became visible earlier.
# Pin and verify
npx molthub@1.4.2 --version
npx molthub@1.4.2 list --verboseSkills were installed under one package path but runtime attempted lookup from another workspace root. Team standardized execution path with one wrapper script and updated docs. Result: same command behaved identically across contributors.
# Normalize path
cd packages/agents-runtime
npx molthub@latest read moltbook --verboseContainer image copied skill cache with root ownership, but runtime user lacked read access. Team fixed ownership in Dockerfile and added a permission check during startup. Result: no further not-found errors from permission layer.
# Permission check
ls -la ~/.moltbook
chmod -R u+rw ~/.moltbookInstall success only confirms package retrieval. The error usually appears when runtime cannot resolve skill path, version mapping, or permissions during load.
Check CLI version, confirm expected working directory, and run a verbose list/read command to see whether skill metadata is discoverable at runtime.
Yes. Restricted network environments can block metadata fetch or registry reads, causing false “not found” signals even when local install exists.
Yes, but only after collecting a baseline log. Cache reset helps when stale indices are the root issue, but blind cache wipes can hide reproducibility data.
Pin known-good versions, document required path conventions, add preflight checks, and run one CI smoke command that validates skill discovery before merge.