# skills

Berry's always-on skills extension discovers portable
[Agent Skills](https://agentskills.io/specification) and loads their instructions on demand. A skill
is a directory with a `SKILL.md` containing YAML frontmatter and Markdown instructions:

```markdown
---
name: release
description: Prepare and verify a release, including changelog review and release checks.
---

Review changes since the previous release. Read references/checklist.md before proposing
publication.
```

Optional scripts, references, and assets are loaded into model context only on demand. Loading a
host skill copies its bundle to the target machine, but does not execute scripts, install tools, or
grant permissions. Relative resource paths resolve from the listed skill directory, not the
conversation's working directory; ordinary `read` and shell calls work there.

## collections

Berry's own collection belongs to the harness host. Project and shared user collections belong to
the conversation's execution environment.

Precedence, highest first:

1. `.agents/skills/` in the working directory and its ancestors, through the nearest `.git` or `.jj`
   repository root; nearer collections win.
2. `$XDG_CONFIG_HOME/berry/skills/` on the **host**, falling back to the host's
   `~/.config/berry/skills/`. These skills are available to both local and SSH conversations.
3. `~/.agents/skills/` on the **target machine**.

Outside a repository, only the working directory supplies project skills. Collections contain
immediate skill subdirectories; discovery does not recursively search the repository. Symlinked
skills are deduplicated, and shadowed names and malformed files appear in `/skills` diagnostics.

## commands and trust

- `/skills`: list skills, sources, active snapshots, and diagnostics.
- `/skill name`: explicitly load or reload a skill for the next turn, without starting a run.
- `/unskill name`: deactivate a skill.
- `/skills trust`: allow automatic project discovery for this conversation's current repository and
  environment.
- `/skills untrust`: stop automatic project discovery there. Already-loaded skills remain active
  until unloaded.

Host and target user collections are available automatically. Project collections are hidden from
the model's catalog until trusted. An explicit `/skill name` can load a project skill without
trusting the whole repository. For automatic discovery, untrusted project collections are excluded
before resolving name collisions, so a user skill can remain available under the same name.

The model sees names and descriptions, then calls `load_skill({ name })` directly or through
codemode. The tool returns an acknowledgment; the full instructions enter the next model request as
a separate prompt section. Supporting files and scripts require the appropriate existing tools.

## lifetime and limits

Loading records an exact instruction snapshot in conversation history. Active instructions survive
compaction, extension reloads, and restarts, and follow historical forks and rewinds. Editing or
deleting `SKILL.md` does not alter an active snapshot; load it again to pick up edits.

Project and target-user snapshots pause when the conversation moves to another environment and
resume when it returns. Previously recorded snapshots retain this behavior. Moving the working
directory on the same machine does not reinterpret their absolute resource paths. Host snapshots
remain active across environment changes; their pinned bundles are materialized on the new target.
Subagents discover the host collection and their own environment's skills, but do not inherit the
parent's active snapshots or project trust.

Host bundle versions are retained under `$XDG_DATA_HOME/berry/skills/bundles/`, falling back to
`~/.local/share/berry/skills/bundles/`, so historical conversations do not silently acquire newer
resources. Remote copies live under the target's `$XDG_CACHE_HOME/berry/skills/` (default
`~/.cache/berry/skills/`) and can be recreated from those host snapshots. Local conversations use
the host snapshot directly. Reload a skill to capture source edits, including resource-only edits.

Transfers publish only complete bundles and preserve executable script permissions on POSIX targets.
Bundle directories are private. Symlinked skill roots and internal symlinks are supported, but links
escaping the skill directory, cycles, and special files are rejected. Each bundle is limited to 32
MiB, 512 entries, and 16 directory levels. Do not remove host bundle snapshots if historical
conversations still need their resources.

Each `SKILL.md` is limited to 64 KiB; all active snapshots together are limited to 128 KiB,
including paused snapshots. A failed load leaves existing activations intact. Discovery is bounded
to 256 entries per collection and 128 distinct skills, with diagnostics when those limits are
reached.

The required `name` and `description` fields are validated against the standard's character and
length limits. Directory/name mismatches produce warnings. Optional metadata is preserved in the
loaded file; experimental `allowed-tools` and other clients' flags do not change berry's tool
permissions.