docs / troubleshooting

Troubleshooting

Work through the same five steps in order, read what common errors mean before acting, hold the line on cache and snapshot discipline, and — when a report upstream is warranted — prepare a sanitized draft worth filing.

Self-check in five steps

When a command errors or the state looks wrong, run the same five steps. The order is deliberate: scope and working directory explain most surprising results, and environment and versions explain much of the rest.

Confirm the intended scope and working directory. Project commands read and write SKILL.mod and SKILL.lock in the current directory and install into .agents/skills/ there; a command meant to affect the user-wide environment needs --global spelled out.
Run git --version and skillmod --version to confirm Git is available and to record the skillmod version.
Run skillmod list for the full declaration overview; for one entry run skillmod why <selector> to see its source, resolved version, commit, dirhash, installation directory, and the status of each configured target.
Run skillmod verify and record its exit code. list, why, and verify classify every installation directory the same way, so they cannot disagree about a target.
For a planned mutation, rerun it with --dry-run when the command supports it, review the report, and only then decide whether to run it for real.

$ git --version

$ skillmod --version

$ skillmod list

$ skillmod why review

$ skillmod verify

# planned writes: read the dry-run report first

$ skillmod sync --relink --dry-run

Exit codes: verify returns 0 when every checked entry is consistent, 1 for an operational or input error, 2 when drift is detected, and 3 for partial completion where conflicting targets were safely preserved. The full table and the --json report shape live in Automation & CI.

Common errors and what to do

Each row below is one common failure. Read the meaning first, then act; wherever local modifications are involved, the user decides.

Symptom / error	Meaning and handling
`SKILL.mod not found`	The current scope has no manifest. Initialize the intended scope with `init`, or change to the correct project root.
Drift, or a preserved conflict	Inspect the local modifications; do not overwrite them without the user's decision. When `sync` returns 3, read the per-target results: some work completed, while conflicting targets were kept.
Network unavailable	An already materialized immutable snapshot may work offline, validating and installing straight from the local subdirectory; latest-version resolution requires remote references.
Branch rejected	Versions must be immutable: pick a tag, a full commit SHA, or omit the version and let skillmod resolve the latest immutable version.
Address rejected as unsafe	The address must be credential-free: remove the embedded password or token, the query string, and the fragment from the URL, and move an `@version` suffix in `source` into the `version` field. Credentials belong in a Git credential helper, an SSH agent, or the environment.
Manifest validation error	The declaration and the lock are validated when they are read. Report the exact message rather than rewriting the file by guesswork. A `SKILL.lock` without `schemaversion` predates schema versioning and is treated as schema version 1; an explicit unsupported version still needs user intervention.
Snapshot integrity error	Do not suppress it. Preserve the diagnostics; if the source and the local state both look valid, move to the issue-reporting workflow.

Cache and snapshot discipline

One shared content store serves every scope: the cache lives at $SKILLMOD_HOME/pkg/mod/, defaulting to ~/.agents/skillmod/pkg/mod/. Snapshots are readable and immutable, so projects, global skills, and CI runs reuse one copy instead of downloading the same repository again.

prune removes stale installation entries without deleting link targets or snapshots.
There is no automatic cache eviction. Before deleting a snapshot by hand, confirm that no installed link still uses it — a link points at a snapshot shared with every other project on the machine.
Never delete the cache as a shortcut for removing one dependency. Use remove to drop a dependency and prune to clear stale installations.
--dry-run leaves manifests and installations untouched, though remote provenance verification may still populate the shared cache.

$ skillmod remove review --dry-run

$ skillmod prune --dry-run

Detach before editing: auto mode installs links into shared read-only snapshots, so editing through a link edits content shared with every other project on the machine. When an installed skill needs edits, run sync --relink --install-mode=copy for an independent copy.

Prepare a report

File an issue only when the diagnosis points at a defect in skillmod itself and the user agrees. Creating a GitHub issue is an external, public mutation: show the destination repository and the final draft, and obtain explicit authorization immediately before submission.

Reproduce only with commands that are safe for the current state: --dry-run, list, why, and verify. Do not destroy the failing state before collecting diagnostics.

Collect what is available:

skillmod --version and git --version, plus gh --version when GitHub CLI is installed
Operating system and architecture
Installation method and executable path
Project or global scope
The exact skillmod command and its exit code
Expected behavior and actual behavior
Minimal reproduction steps
Whether the behavior is consistent or intermittent

Include the smallest relevant excerpts of SKILL.mod, SKILL.lock, and command output — not whole files by default.

Redact before sharing: remove access tokens, credentials, private repository URLs, usernames, home-directory paths, internal hostnames, and unrelated skill declarations. Never upload an entire private manifest or Git configuration by default.

Diagnostics may print in another language by default. When reproducible in English, setting SKILLMOD_LANG=en makes them easier for maintainers to search, but do not rerun a mutating command solely to translate its output.

Without gh, follow the official installation instructions rather than installing or authenticating it without consent; a user who does not want GitHub CLI gets the same draft prepared and files it on the repository's issues page. Search for duplicates before filing a new one:

# search open and closed issues with keywords from the symptom

$ gh issue list --repo huija/skillmod --state all --search "<keywords>" --limit 20

Report structure: Summary (one or two sentences on the defect and its impact) · Environment (skillmod and Git versions, OS and architecture, installation method, scope) · Steps to reproduce · Expected behavior · Actual behavior · Command output (sanitized output and exit code) · Additional context (minimal sanitized manifest excerpts). Title the issue as <command>: <observable problem> — a factual statement, not an unproven root cause.