lazyskills

README

Lazy Skills

Mission control for agent skills to stay lazy.

"I don't debug broken skills by hand - I have a TUI to be disappointed for me."

🌴 Overview

LazySkills is a terminal UI for agent skills. It shows what skills are installed, which agents can see them, why visibility may be broken, and provides guarded actions for common skill operations — all from one screen.

It is designed to complement the official skills CLI, not replace it.

✨ Features

✅ Fast, keyboard-driven Bubble Tea TUI
✅ Project and global skill inventory
✅ Agent compatibility diagnostics based on the upstream skills registry
✅ Visibility reasons per agent, including missing links, broken symlinks, unsupported global installs, and ghost agent-directory skills
✅ SKILL.md preview with safe terminal sanitization
✅ Responsive panes and scrollable details
✅ Source/repo group headers in the skill list
✅ Guarded actions — refresh/rescan, open in $EDITOR, reinstall/update, remove, and bulk update/remove via the official skills CLI
✅ Source/repo-aware selection for grouped workflows
✅ Structured command execution with confirmation, captured output, and rescan after successful mutations

🛠️ Installation

Homebrew

brew install --cask alvinunreal/tap/lazyskills

macOS / Linux install script

curl -fsSL https://raw.githubusercontent.com/alvinunreal/lazyskills/main/scripts/install.sh | sh

The script installs to /usr/local/bin by default and verifies the release checksum. To install somewhere else:

curl -fsSL https://raw.githubusercontent.com/alvinunreal/lazyskills/main/scripts/install.sh | sh -s -- -b ~/.local/bin

Windows PowerShell

iwr https://raw.githubusercontent.com/alvinunreal/lazyskills/main/scripts/install.ps1 -useb | iex

The PowerShell installer installs to %LOCALAPPDATA%\Programs\lazyskills\bin and adds it to your user PATH.

Windows Scoop

scoop bucket add alvinunreal https://github.com/alvinunreal/scoop-bucket
scoop install lazyskills

Windows WinGet

winget install alvinunreal.lazyskills

WinGet availability may lag behind GitHub Releases because new versions are submitted to microsoft/winget-pkgs as pull requests.

Go

go install github.com/alvinunreal/lazyskills/cmd/lazyskills@latest

Nix experimental

Run directly from GitHub:

nix run github:alvinunreal/lazyskills

Or from a local checkout:

nix run

Manual download

Download a binary archive from GitHub Releases, verify it with checksums.txt, and place lazyskills on your PATH.

Linux packages

LazySkills publishes .deb and .rpm packages for Linux amd64 and arm64 releases.

Debian / Ubuntu:

curl -LO https://github.com/alvinunreal/lazyskills/releases/download/v0.1.0/lazyskills_0.1.0_linux_amd64.deb
sudo apt install ./lazyskills_0.1.0_linux_amd64.deb

Fedora / RHEL / openSUSE:

curl -LO https://github.com/alvinunreal/lazyskills/releases/download/v0.1.0/lazyskills_0.1.0_linux_amd64.rpm
sudo dnf install ./lazyskills_0.1.0_linux_amd64.rpm

Use the arm64 package instead on ARM Linux machines.

Build from source

go build -o lazyskills ./cmd/lazyskills

Then run:

./lazyskills

Or scan as JSON:

./lazyskills scan --json
./lazyskills scan --json --cwd /path/to/project

Check the installed version:

lazyskills version

⌨️ Usage

lazyskills [--cwd <path>]
lazyskills scan --json [--cwd <path>]

Common TUI keys:

Key	Action
↑/↓, j/k	Move selection
space	Mark/unmark skill for bulk actions
s	Mark all skills from the current source/repo
o	Open current skill in $EDITOR
u	Update current skill, or marked skills if any are selected
x	Remove current skill, or marked skills if any are selected
tab, shift+tab, ←/→	Change project/global scope filter
a	Cycle agent filter
A	Reset agent filter to all agents
/	Search skills
c	Show guarded actions
enter	Run selected action when actions are visible
r	Refresh scan
?	Toggle help
q	Quit

Mutating actions open a centered confirmation prompt. Press Enter for the default yes, or type y, yes, or the displayed phrase. Press n or Esc to cancel.

The skill list groups adjacent skills by source/repo when lock metadata is available. Skill details also show the exact folder and ref. Use s to mark every skill from the current source/repo, then u or x to update or remove that group with confirmation.

⚡ How actions work

LazySkills delegates install/update/remove behavior to the official skills CLI. It resolves commands as:

1. skills if available on PATH
2. npx --yes skills as fallback

Commands are executed as structured argv, not shell strings. Output is captured, sanitized, capped, and displayed in the TUI. Successful mutations trigger a rescan.

🤖 Supported agents

LazySkills mirrors the upstream vercel-labs/skills agent registry, including universal .agents/skills agents, agent-specific skill directories, global support, and installed-agent detection heuristics.

The registry is manually ported for now. A generated parity check is a planned follow-up.

🛟 Safety and limitations

• LazySkills does not reimplement remote clone/install/update/remove logic in Go.
• Search/marketplace flows are not implemented.
• skills use integration is not implemented.
• Agent cycling is functional but not yet a searchable picker.

🧪 Development

go test ./...
go build ./cmd/lazyskills

🚢 Releases

LazySkills uses GoReleaser to publish cross-platform binaries, checksums, GitHub Releases, and the Homebrew formula.

Release a new version by pushing a SemVer tag:

git tag v0.1.0
git push origin v0.1.0

The release workflow builds:

• macOS Intel and Apple Silicon
• Linux amd64 and arm64
• Windows amd64 and arm64
• Linux .deb and .rpm packages

Nix users can run LazySkills with nix run github:alvinunreal/lazyskills once the flake dependency hash is finalized.

Homebrew publishing requires the repository secret HOMEBREW_TAP_GITHUB_TOKEN with permission to push to alvinunreal/homebrew-tap.

Scoop publishing requires the repository secret SCOOP_BUCKET_GITHUB_TOKEN with permission to push to alvinunreal/scoop-bucket.

WinGet publishing requires the repository secret WINGET_TOKEN, a classic GitHub token with public_repo scope. The first WinGet submission may need to be created manually before automated updates are accepted.