> ## 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:

```bash theme={null}
to11 skill sync --dry-run   # what a sync would do, without writing
to11 skill sync             # do it, and report each skill
```

`installed`, `updated`, `replaced`, `removed`, `unchanged`, `unmanaged` and `disabled` need nothing from you. The states below do. Every state is defined in the [output reference](/docs/reference/cli/output#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.
</Warning>

## `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`](/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, then [release it](/docs/skills/publishing-skills#release-it) if others should have 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 you put there yourself. Your copy stays; the repository's is not installed, and sync still exits `0`.

To get the repository's version as well, give your home skills a [`prefix`](/docs/skills/choosing-skills#avoid-a-name-you-already-use) so the names no longer collide. If the colliding entry is one you created, rename or move it.

Turning the skill off in `~/.to11/skills.yaml` does not help when both configurations name the same project the same way — both by `workspace/project`, or both by id: a disable in your own file also turns the repository's copy off, so neither is installed.

## `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. Turn off 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` — nothing is released on that label

The project has the skill, but the label you follow carries no version of it yet. Someone who can publish needs to release a version on that label — `to11 skill release <slug> --label <label>`; without `--label`, `release` moves the label of the project entry in their configuration, which may be a different one — or, to use it now, pin a stored version with `version:` or follow a label that has one.

## `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`](/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 and label are 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

<CardGroup cols={2}>
  <Card title="Output reference" icon="list" href="/docs/reference/cli/output#states">
    Every state, the version column, and the JSON form.
  </Card>

  <Card title="Errors & exit codes" icon="triangle-alert" href="/docs/reference/cli/errors">
    What a failure looks like, and what keeps working when one happens.
  </Card>
</CardGroup>


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