> ## Documentation Index
> Fetch the complete documentation index at: https://to11.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting skills

> Find out why a skill is missing, stale or left alone, and fix each state in to11 skill list that needs you.

Start with the list. It has a row for every skill your configuration names — including the ones that did not arrive — and the state says why:

```bash theme={null}
to11 skill list
```

An automatic refresh fails silently, so an explicit sync is how you see an error. It reports each skill:

```bash theme={null}
to11 skill sync
```

`installed`, `updated`, `replaced`, `removed`, `unchanged`, `unmanaged` and `disabled` need nothing from you. The states below do. Every state is defined in the [output reference](https://to11.ai/docs/reference/cli/output.md#states).

> [!WARNING]
>
> `to11 skill sync --force` applies to the whole run, not to one skill. In one pass it replaces every `conflict` directory and discards the edits in every `dirty` skill. It never deletes the files an `orphaned` skill left behind. Run `to11 skill list` first, and move anything you want to keep before you force.

## `conflict` — something else is in the way

A directory to11 did not write already has the skill's name. Sync leaves it alone and names the path.

* **It is yours and you want to keep it:** move or rename it, then sync again. Or set a [`prefix`](https://to11.ai/docs/skills/choosing-skills#avoid-a-name-you-already-use) so every skill from to11 lands under a different name.
* **It is an old copy you no longer need:** delete it and sync again, or — once nothing else in the list is `dirty` or `conflict` that you want to keep — let to11 replace it:

  ```bash theme={null}
  to11 skill sync --force
  ```

## `dirty` — you edited an installed skill

A file in a skill to11 installed no longer matches what was delivered. Sync leaves the whole skill alone rather than mixing your edit with a new version.

* **Keep the edit:** store it as a new version, which everyone following the project [receives](https://to11.ai/docs/skills/publishing-skills.md#who-receives-it):

  ```bash theme={null}
  to11 skill store incident-triage --dir ~/.claude/skills/incident-triage
  ```

* **Discard the edit:** delete the skill's directory and run `to11 skill sync` to reinstall it, or use `to11 skill sync --force` (see the warning above).

## `orphaned` — files of yours left where a removed skill was

The skill left your configuration. Sync removed the files it wrote, and left the ones the row lists: files you changed, or added, hidden ones included. A `.DS_Store` written by macOS Finder is removed with the skill. No flag removes the rest. Copy anything you want to keep, then delete them yourself; the next sync removes the empty directory.

## `shadowed` — a repository skill has the same name as one of yours

Inside a repository, a skill the repository's configuration asks for has the same name as an entry in your home location's skills folder for the same agent — a skill to11 delivered, or a directory, a loose `<name>.md` file or a link another tool or you put there. Your copy stays; the repository's is not installed, and sync still exits `0`.

The sync says so once per location, not once per skill: `! N not installed — your own skills already use these names`, the names, and a `held by` line naming the folder and whether what is there is a to11 skill your home follows or something to11 did not install. With `--format json`, each such row carries `heldBy`, the path that holds the name.

To get the repository's version as well, set a [`prefix`](https://to11.ai/docs/skills/choosing-skills#avoid-a-name-you-already-use) in the repository's `.to11/skills.yaml` so its skills land under names that do not collide — that works whatever holds the name. Your home's own to11 skills can take a prefix instead. If the colliding entry is one you or another tool created, rename or remove it.

Disabling the skill in `~/.to11/skills.yaml` removes your own copy, and the same sync installs the repository's — when what held the name was a skill to11 delivered to your home. With `enforced: true` beside the disable, neither is installed: an enforced disable keeps the skill out of the repository too, when both configurations name the same project the same way (both by `workspace/project`, or both by id).

## `ambiguous` — two entries want the same name

More than one project entry in one configuration resolves to the same slug, so to11 installs none of them rather than picking one by the order of the file. Disable all but one under their project entries, or name the skill under only one project. Sync exits `1` until it is resolved.

## `not-found` — the project has no such skill

The slug is misspelled, or the skill was deleted. Check it against the project's **Skills** page in the dashboard, then fix or remove the entry.

## `no-label` — the skill has no stored version yet

The project has the skill, but nobody has stored a version of it, so `latest` points at nothing. The row reads `<project> has it, but no version is stored yet`, and the summary counts it as `not published`. Someone who can publish needs to store one: `to11 skill store <slug> --dir <folder>`.

## `gone` — a skill you picked is no longer there

You named the skill with its own `label` under a project entry that has no `label` of its own, and the project deleted it, or it has no stored version. The copy you have stays, the row reads ``no longer published — kept v<n>; `to11 skill sync --prune` removes it``, and the sync exits `0`. At a terminal the sync asks `Remove <slug>, no longer published?` — `Remove skills no longer published?` for several; `to11 skill sync --prune` removes it without asking — the files to11 wrote (what you changed stays, `orphaned`) and its line in `skills.yaml`, with the project entry when nothing is left in it. When it is the only line the file has, it is turned off instead (`disabled: true`), since a file naming no project is invalid; the files go all the same.

## `symlink` — the destination is a link

to11 never writes through a symbolic link. Either the skill's directory, or the agent's skills directory itself, is a link. Replace the link with a real directory, or give that target a different `path` in [`targets`](https://to11.ai/docs/reference/cli/configuration#every-key). Sync exits `1` for a skill your configuration asks for.

## `failed` — something could not be done

The row's reason says what broke:

* **A fetch, write or delete during `to11 skill sync`.** Fix the cause — disk space, permissions, network — and sync again; what did succeed is already recorded.
* **`… resolved no project`.** The configuration names a project nothing could look up. Check the `project` entry against the dashboard; syncing again will not clear it.
* **`cannot inspect <path>`** (shown by `list` too). Check that the agent's skills directory is a directory, not a file, and that you have permission to open it.

## A skill you expected is not listed at all

* **Your configuration does not name it.** Check that its project is in `~/.to11/skills.yaml` or the repository's `.to11/skills.yaml`.
* **You cannot access the project.** The install fails and says so, and `to11 skill sync` exits `1`. Ask for access to the project.

## Next steps

> [card] [Output reference](https://to11.ai/docs/reference/cli/output.md#states)
>
> Every state, the version column, and the JSON form.

> [card] [Errors & exit codes](https://to11.ai/docs/reference/cli/errors.md)
>
> What a failure looks like, and what keeps working when one happens.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.