Valet|Docs
Sign up

CLI: Skills

A skill is a versioned bundle of instructions — a SKILL.md plus any supporting files — that an agent loads at deploy time. Agent skill instances are configured in Valet and materialized during deploy.

Skill refs

Catalog refs create scoped instances; org refs attach shared instances:

  • catalog:<name>[@vN|@latest] — a curated catalog skill
  • org:<name>[@vN|@latest] — an org skill snapshot

An unpinned or @latest ref resolves to the newest version at deploy time; @vN pins a specific version.

List skills

valet skills --agent <agent>    # the agent's effective skills
valet skills --org <org>        # org-scoped skill instances

Browse the catalog

valet skills catalog [--org <org>]

Lists Valet-curated skill bundles that can be attached to agents with valet skills attach catalog:<name>.

Attach and detach

valet skills attach <source> [--agent <agent>] [--org <org>]
valet skills detach <source-or-name> [--agent <agent>]

Detach accepts the original source ref (such as catalog:research) or the materialized skill name (such as research). The org skill snapshot or catalog entry is not deleted.

$ valet skills attach catalog:research --agent assistant --org acme
Attaching catalog:research to assistant agent in acme org... done, catalog:research

$ valet skills attach org:brand-voice@v2 --agent assistant
Attaching org:brand-voice@v2 to assistant agent... done, org:brand-voice@v2

Skill info

valet skills info <name> [--org <org>]

Shows an org skill's description, the origin repository it was snapshotted from, the version history, and the agents whose valet.yaml declares an org:<name> ref for it. The Ref line is the pinned form of the latest version, ready to declare in a manifest's skills: list.

$ valet skills info premortem
=== Skill: premortem in acme org
  Name:            premortem
  Description:     Run a premortem on any plan
  Origin:          github:https://github.com/acme/premortem
  Latest version:  v2
  Ref:             org:premortem@v2
=== Versions (2)
  v2  4bf5c2…  2048 bytes  2026-07-02T00:00:00Z
  v1  9d01ae…  1024 bytes  2026-07-01T00:00:00Z
=== Used by (1)
  support-bot