# ivar skill
> Installed, updated and materialised locally — how repo skills stay namespaced by origin, and how the same set follows you into whichever harness you open.
Source: https://ivar.run/docs/reference/skill

import { Callout } from 'fumadocs-ui/components/callout';

A **skill** is a folder with a `SKILL.md` that teaches an agent how to do
something in your codebase. `ivar` installs them, tracks where they came from,
and materialises them into each harness's native location — so the same set
follows you across harnesses instead of being re-installed per tool.

## Where skills come from

Two origins, and the difference matters when two of them share a name.

**Repo skills** ship inside a repo and keep their origin in their name:

```
api--openapi-contract
web--openapi-contract
```

Both repos can ship an `openapi-contract` skill and neither shadows the other.
Without the prefix they land in the same folder, one silently wins, and you find
out much later that the agent has been following the wrong one.

**Hall skills** live in the hall's shared skills directory, mount flat, and
apply to the whole session — commit conventions, review checklists, anything
that is not about one repo in particular.

## Install

```sh
ivar skill add https://github.com/acme/skills --path skills/commit-style --ref v2
```

`--path` points at a sub-folder when the repo holds more than one skill, and
`--ref` pins to a branch, tag or sha. Skills installed this way are **external**:
`ivar` remembers the source and can update them.

```sh
ivar skill create commit-style   # scaffold an authored skill instead
```

## Update and detach

```sh
ivar skill update              # bring external skills to their tracked ref
ivar skill detach commit-style # turn an external skill into an authored one
ivar skill remove commit-style
```

<Callout title="Detach before you edit">
  Editing an external skill in place means the next `update` overwrites your
  changes. `detach` converts it into a local, authored skill that `ivar` no
  longer tracks against a remote — then it is yours.
</Callout>

## Materialise

```sh
ivar skill sync
```

Writes the hall's skills into the native location each tool expects. This is the
same step `ivar sync` performs as part of bringing a checkout in line with the
manifest, and the seam a harness uses when it materialises agent config: a
subprocess plus a filesystem convention, nothing more.

## Inspect

```sh
ivar skill list     # what is in the hall's shared skills directory
ivar skill status   # external, authored, or stale
ivar skill doctor   # broken links, missing refs, and suggested fixes
```