agentctl

agentctl

agentctl is a terminal application for browsing and installing skills for coding agents. It includes a local catalog, can discover skills from remote Git repositories, and installs each skill only into the directories used by the selected agents.

The interactive interface is built with Bubble Tea. It provides catalog browsing, multi-selection, installation scope selection, and progress feedback.

Install

Linux

Install the latest Linux release without Go or a manual download:

curl -fsSL https://raw.githubusercontent.com/hsm-gustavo/agentctl/main/install.sh | sh

The installer verifies the downloaded archive with SHA-256 and installs the binary in $HOME/.local/bin. Add that directory to your PATH if necessary.

To choose a different directory or a specific version:

curl -fsSL https://raw.githubusercontent.com/hsm-gustavo/agentctl/main/install.sh | \
  AGENTCTL_INSTALL_DIR="$HOME/bin" AGENTCTL_VERSION=v0.1.0 sh

Windows

Download the agentctl_windows_amd64.zip or agentctl_windows_arm64.zip archive from the latest release, verify it against checksums.txt, then place agentctl.exe in a directory on your PATH.

Go

If you have Go 1.25 or newer, install the latest version with:

go install github.com/hsm-gustavo/agentctl@latest

Build from source

go build -o agentctl .

You can also run the application without building a binary:

go run .

Building from source requires Go 1.25 or later. Git is required for Git-backed catalog entries and remote repositories.

Commands

Browse the catalog

agentctl list

Use the arrow keys or j/k to browse the available skills.

Install from the catalog

agentctl install

Select one or more skills, then choose whether to install them in the current project or globally. Without an --agent value, agentctl uses the universal agent destination.

Pass one or more agents explicitly with repeated --agent flags:

agentctl install --agent codex --agent claude-code

Use --global to skip the scope prompt and install into each agent's user-level directory:

agentctl install --global --agent codex --agent claude-code

Install from a remote repository

Remote repositories must store skills as direct children of skills/, with a SKILL.md file in each skill directory.

repository/
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

Use --remote with the provider:owner/repository format. The remote skills are shown in the same interactive selector:

agentctl install --remote github:owner/repository

Use --skill to install specific remote skills without opening that selector. Values may be comma-separated, and the flag may be repeated:

agentctl install \
  --remote github:owner/repository \
  --skill skill-one,skill-two \
  --agent codex

Installation directories

Agent locations are defined in one central registry. Project installations use each agent's project skill directory; agents that share the universal convention use <project>/.agents/skills.

Global installations resolve the appropriate user-level directory for the selected agent. The resolver honors HOME, XDG_CONFIG_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, VIBE_HOME, HERMES_HOME, and GROK_HOME, with sensible fallbacks when they are unset.

When multiple agents map to the same physical directory, agentctl installs each skill there once.

Safe replacement

If a skill already exists at a destination, agentctl stages the new version in a temporary directory, moves the existing installation to a temporary backup, and promotes the staged version. The old installation is removed only after the new one is valid.

This is a full replacement: files that exist only in the previous skill version are not retained. If promotion fails, agentctl restores the previous installation.

Releases and package documentation

Releases include Linux and Windows binaries for amd64 and arm64, plus a checksums.txt file. The source module and command documentation are available on pkg.go.dev after a tagged release is indexed.

License

agentctl is available under the MIT License.

Development

Run the complete test suite and static checks with:

go vet ./...
go test ./...