Install and update agent skills, resolved to exact versions.

Overview · Quick look · Install · Usage · Requirements · Documentation · Contributing · License

Declare skills once, restore exact locked content with install, and preview upstream changes before applying an update. skill supports Codex, Claude Code, Cursor, Gemini CLI, and OpenCode through agents-tools/core.

This is the skills edition of agents. skill add|list|remove|update|init matches agents skills commands; skill install|update|doctor runs the shared skill operations. Instruction selections, locked instruction records, and target files remain untouched. skill watch matches agents watch and shares its subscription state, including reports of instruction units and well-known artifacts.

Install two skills from a local Git source, watch it for changes, and apply an upstream update:

Source and HEAD builds require macOS 15 or later. Stable Homebrew releases retain their published requirements; the formula's macOS minimum changes with the release that raises it.

Install the latest stable release from the Homebrew tap:

brew install skill-cli/tap/skill-cli
skill --help

For a development build of master, use:

brew install --HEAD skill-cli/tap/skill-cli

The tap provides skill and swift-skill. Use either executable directly; swift skill depends on the active Swift driver's external-command dispatch. See the tap documentation for packaging and channel details.

skill add https://github.com/anthropics/skills.git --all --agent codex
skill list
skill list --scope user --json
skill watch add https://github.com/anthropics/skills.git
skill watch
skill watch diff https://github.com/anthropics/skills.git
skill watch seen https://github.com/anthropics/skills.git
skill install
skill update
skill update pdf --apply
skill remove pdf
skill init my-skill
skill doctor --root /path/to/project-a /path/to/project-b --json

Project scope uses the current directory and stores agents.json, agents.resolved, agents.watch, and cache/ under .agent/. --scope user uses ~/.agents/. Keep state and caches out of version control.

add installs in link mode for the recipients already recorded for that skill or source, otherwise for the declaration's default agents (initially Codex and Claude Code). Repeat --agent to choose recipients. link and copy install committed, pinned content from Git sources; edit links a live local directory. An unnamed add installs the only discovered skill or prints choices when there are several. --all follows future membership changes on update.

watch subscribes without installing content, reports changes since the last watch seen, and previews file differences. watch remove keeps installed skills and instructions. Scheduling checks is left to the caller.

Commands are non-interactive. Updates preview by default; --apply prints the differences before writing. See the CLI reference for options, JSON schemas, errors, and exit codes.

0.3 does not read 0.2 state or replace 0.2 installations. Follow Upgrading from 0.2 to move them.

Install the companion that teaches agents this command surface:

skill add skill-cli/cli --branch master --path skills/skill-cli --scope user --agent codex

For live local development:

skill add . --path skills/skill-cli --scope user --agent codex --mode edit

• macOS 15 or later
• Swift 6.3 or later to build from source
• Git for source repositories

• Documentation index
• CLI reference: commands, options, output, state, and JSON schemas
• Package architecture: ownership and data flow
• Releasing skill: dependency, version, and release checks
• Presentation assets: README terminal session and repository social preview
• Changelog: unreleased changes and earlier releases

Follow the family change flow and read Contributing for the development loop and required CI contexts. The development section gets a local build running.

swift build
swift run skill --help
env -u CODEX_HOME -u CLAUDE_CONFIG_DIR -u XDG_CONFIG_HOME -u XDG_STATE_HOME -u XDG_CACHE_HOME swift test

The package pins a core revision during development. Release preparation changes this to a published version range. The build-time version is BuildInfo.version in Sources/CLI/EntryPoint.swift.

skill is available under the MIT License.