# Troubleshooting ## `conda skill` is not recognized Check `conda --version` and the environment that provides the executable. The plugin needs conda 26.9 or newer and Python 3.11 or newer, and must be installed in that same environment. Follow {doc}`installation`, then run `conda skill --help`. Check whether `CONDA_NO_PLUGINS` or your invocation's `--no-plugins` option disables external plugins. Installing the plugin in a skill source environment or a conda-workspaces development environment does not register it with base conda. ## `conda pypi` is not recognized or an editable install fails Install `conda-pypi` 0.12 or newer from conda-forge into the environment that runs conda, as shown in {doc}`installation`. Check `conda pypi install --help` for `-n`, `-p`, and `-e`. Older versions had environment-selection bugs. Keep the explicit target on both prerequisite and editable-install commands. For a checkout, run `conda pypi install -n base -e .` from its root, substituting the actual conda-owning prefix with `-p` when needed. Editable installs do not resolve runtime dependencies, so install the guide's `rich` and `ruamel.yaml` prerequisites too. ## `list` finds no skills Use `conda skill list -p ` to make the source explicit. Check that the intended package was installed in that prefix with `conda list -p `. Conda's package record must contain the exact path `share/agent-skills//SKILL.md`. A manually copied directory or pip-only installation is not enough. Compare your installed layout and recipe with {doc}`package-a-skill`. To inspect project links instead of source skills, use `status` rather than `list`. Discovery fails if a package contains malformed frontmatter, two packages claim the same skill, or a skill path escapes its environment. Correct or replace the source package through conda before retrying. ## Linking refuses an existing destination Run `conda skill status` with the same `--backend` and `--global` settings used for linking. A regular file or directory, a link to a different source, and a broken link all block linking. There is no force flag. If the entry belongs to another tool, manage it through that tool or choose a different project or backend. Review and preserve an existing directory's contents before removing it. The plugin reuses a link to the same resolved source without replacing it. ## A link is broken after moving or deleting its source `conda skill status` works without the source environment and reports the destination and resolved target. Check whether the source package was removed, the environment moved, or the project moved independently of a relative target. A target directory lacking `SKILL.md` is also reported as broken. If the original package-owned source still exists, remove its link with `conda skill unlink ` before changing the source. The command identifies the source from the destination symlink, independently of your active environment. Broken or unverifiable targets are refused with guidance to inspect status before using `--force`. For a project-local `review-notes` link, inspect the destination and target: ```sh conda skill status ``` Confirm that the row identifies the stale symlink you intend to remove. If it does, remove only that link: ```sh conda skill unlink review-notes --force conda skill status ``` Use the same `--backend` and `--global` settings on these commands as for the original link. `--force` never removes a regular file or directory, deletes package files, or bypasses redirected-parent checks. If inspection shows a real directory, stop and preserve its contents. After cleanup, `conda skill link -p ` can create a link from another valid source. Substitute an actual discovered skill name and source prefix for the placeholders, or omit `-p` to use the active environment. ### Manual inspection and removal If the plugin is unavailable, inspect the exact symlink with your shell before removing it manually: ::::{tab-set} :::{tab-item} POSIX ```sh ls -ld .agents/skills/review-notes readlink .agents/skills/review-notes ``` After confirming that this is the stale symlink you intend to remove: ```sh unlink .agents/skills/review-notes ``` ::: :::{tab-item} PowerShell ```powershell Get-Item -Force -LiteralPath .agents/skills/review-notes | Format-List FullName,LinkType,Target ``` After confirming that the entry is the stale directory symbolic link you intend to remove, use Command Prompt's directory-link removal without `/s`: ```powershell cmd /c rmdir .agents\skills\review-notes ``` ::: :::: Adapt the exact path for your backend and scope, and check that its parent directories do not redirect elsewhere. Do not use manual removal to bypass the plugin's redirected-parent refusal. Do not add a trailing separator or use recursive deletion: the operation should remove the link itself, not traverse its target. If inspection shows a real directory, stop and preserve its contents. ## A client directory is redirected The plugin rejects symlinked or redirected components such as `.agents` or `.agents/skills`. This check applies to status as well as mutations. Inspect the directory structure outside the plugin and use a destination whose client directories are real directories under the intended root. Do not remove shared client-directory links without understanding the other tools that use them. ## Windows cannot create a symlink Enable Developer Mode or obtain directory-symlink privileges according to your system policy. The plugin reports the operating-system error and does not silently copy the skill. Source and destination on different drives use an absolute target, so moving that source later requires relinking. ## Unlinking fails or leaves files behind Use the same backend and scope as linking. No source flag or activation is needed. The destination symlink's target must match a recorded conda skill unless you explicitly use `--force` after inspection. If the link is already absent, unlinking succeeds without changing anything or looking up a source. A regular file, directory, or redirected parent is refused even with `--force`. Unlinking leaves source package files and empty `.agents/skills/` or `.claude/skills/` directories intact. To uninstall the package too, follow {ref}`remove-a-skill-completely`. Use the package name from `conda skill list`, not necessarily the skill name, and review conda's removal plan before confirming. ## Output is JSON unexpectedly The plugin follows conda's configured JSON mode, including `CONDA_JSON=true`. Check that setting and your conda configuration if you expected a table. In scripts, check the command's exit status and parse the entire JSON document. Errors use conda's error response rather than the plugin's success shape. ## Skill-forge metadata fails to load During local testing with conda-rattler-solver 26.10.2, channel loading failed with `Object of type bytes is not JSON serializable` while processing `attestations_sha256`. This happened before conda-skills ran. If you encounter that exact error, retry with libmamba for the affected package command: ```sh conda create --solver libmamba -n skill-demo --override-channels -c https://prefix.dev/skill-forge -c conda-forge "agent-skill-polars==0.0.8" ``` As in the tutorial, use an unused environment name. Inspect `conda env list` before retrying if the failed command may have created one. For `conda workspace lock`, which has no solver flag, select libmamba for the current invocation in Bash or zsh: ```sh CONDA_SOLVER=libmamba conda workspace lock ``` In PowerShell, set `$env:CONDA_SOLVER = "libmamba"` for the command and restore its previous value afterward. This workaround changes neither package ownership checks nor signature verification policy. Do not disable plugins or verification to bypass an integrity failure.