Skip to content

troubleshooting.md

Latest commit

 

History

History
151 lines (102 loc) · 4.52 KB

troubleshooting.md

File metadata and controls

151 lines (102 loc) · 4.52 KB

Troubleshooting

Docs Index · CLI Reference · Config Reference

Common issues when running skillpm locally.

sync --strict exits with code 2

Meaning: execution completed, but risk posture failed strict policy.

What to do:

  1. Re-run with JSON output and inspect risk fields.
  2. Review recommended command(s) in JSON (recommendedCommand / recommendedCommands).
  3. Resolve hotspot source, then re-run strict gate.
./bin/skillpm sync --strict --json > sync.json

Non-zero exit code that is not 2

Meaning: runtime/validation/execution error.

What to do:

  1. Run doctor to auto-detect and fix environment drift.
  2. Retry in dry-run mode to isolate planning issues.
  3. Check source reachability and local file permissions.
./bin/skillpm doctor
./bin/skillpm sync --dry-run

Environment drift / stale state

Symptoms: injections reference uninstalled skills, orphan directories in installed/, adapter's injected.toml out of sync with state.

Fix: run doctor — it detects and auto-repairs all of these in one pass:

skillpm doctor

The doctor runs 7 checks in dependency order:

  1. config — creates missing config, enables detected adapters
  2. state — resets corrupt state
  3. installed-dirs — removes orphan dirs and ghost state entries
  4. injections — removes stale refs
  5. adapter-state — re-syncs injected.toml
  6. agent-skills — restores missing skill files
  7. lockfile — reconciles lock with state

Doctor is idempotent — run it again and the second pass will show all [ok].

Source add/update failures

Likely causes:

  • invalid URL
  • auth/network failure
  • unsupported source type

Checklist:

  • verify URL is reachable
  • re-run with a known-good public repo
  • confirm --kind matches source type

Install blocked by security scan (SEC_SCAN_*)

Meaning: the skill content triggered one or more security scan rules. See Security Scanning for the full rule reference.

Error codes:

  • SEC_SCAN_CRITICAL: critical finding (e.g. curl|bash, reverse shell) — cannot be bypassed
  • SEC_SCAN_BLOCKED: high or medium finding — may be bypassed with --force (except critical)

What to do:

  1. Read the error message to identify which rule and pattern triggered the block.
  2. Inspect the skill content manually to verify whether the flagged pattern is legitimate.
  3. For medium-severity findings you trust, re-run with --force:
./bin/skillpm install my-repo/admin-tool --force
  1. To disable a specific rule, add it to config:
[security.scan]
disabled_rules = ["SCAN_DANGEROUS_PATTERN"]
  1. To disable scanning entirely (not recommended):
[security.scan]
enabled = false

Install or upgrade appears stale

Checklist:

  • run source update first
  • verify lock/state files are writable
  • confirm selected ref/version exists upstream

See Project-Scoped Skills for the full project workflow.

Project scope errors

PRJ_NO_MANIFEST: no project manifest found

You used --scope project but no .skillpm/skills.toml exists above the current directory.

Fix: run skillpm init in the project root first.

PRJ_INVALID_SCOPE: invalid scope "..."

The --scope flag only accepts global or project.

Project install doesn't affect global

This is by design. Project and global scopes are fully isolated with separate state directories, lockfiles, and injection paths. Use --scope global to explicitly target global scope from within a project.

Publish failures

SRC_PUBLISH: CLAWHUB_TOKEN environment variable required for publishing

skillpm publish needs a bearer token in the environment.

Fix:

export CLAWHUB_TOKEN="your-token"
skillpm publish ./my-skill --version 1.0.0

SRC_PUBLISH: source "..." not found

The named registry source does not exist in your config.

Fix:

  1. Check configured sources with skillpm source list.
  2. Add or update the target registry source.
  3. Re-run skillpm publish --source <name>.

Known Limitations

  • No cloud-hosted control plane (local-first operation only).
  • No built-in scheduler or leaderboard in v4.x; use source update, search, and manual or external automation around sync.
  • Adapter behavior can differ across runtimes; validate in your target environment.
  • Automation consumers must parse JSON output; human-readable text is not a stable API.
  • Strict risk policy is intentionally conservative and may require manual follow-up in edge cases.