skills

Berry's always-on skills extension discovers portable Agent Skills and loads their instructions on demand. A skill is a directory with a SKILL.md containing YAML frontmatter and Markdown instructions:

---
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.