lazyskills: a terminal view of the skills your coding agents can actually see

The problem it addresses: skills installed but not visible

LazySkills is described as a blazing-fast terminal UI for managing agent skills, and the description of what it gives you is specific: one place to see what is installed, which agents can use each skill, why visibility may be broken, and what actions are safe to run next.

The third of those is the interesting one, and it points at the reason this kind of tool exists. Coding agents discover skills from directories that each agent defines, and the same skill can be present in several places at once: a project scope for one repository, a global scope for your user directory, a universal scope, and agent-specific directories for each tool. When a skill is installed but the agent does not pick it up, the cause is almost always a scope or path mismatch, and the diagnostic is a matter of comparing several directory trees by eye.

The feature list makes that explicit. You can see every skill in one place across project, global, universal and agent-specific skills. You can check agent visibility by switching agents and seeing which skills are actually usable by Claude Code, OpenCode, Codex, Cursor, Gemini CLI, and many more. And you can spot broken installs fast, with the tool highlighting missing SKILL.md files, invalid frontmatter, broken symlinks, missing lock entries and ghost agent skills.

That last category is the one that distinguishes this from a file browser. A ghost agent skill is one that the agent believes it has but which no longer exists on disk, and a missing lock entry is one that a lock file claims but that is not present. These are the states that make a skill system confusing to debug by hand.

The primary language is Go, the module requires Go 1.26.3, the licence is MIT, the homepage is lazyskills.sh, and the recent releases are v1.2.0 from 2026-09-26, v1.1.0 from 2026-09-07 and v1.0.3 from 2026-09-06. The last push was on 2026-09-26, so the project is young and moving quickly.

Installing it, and the TUI you land in

There are four install routes, and they cover the usual platforms.

For macOS and Linux, the recommended route is the install script:

curl -fsSL https://lazyskills.sh/install | sh

Homebrew is the alternative:

brew install --cask alvinunreal/tap/lazyskills

On Windows, a PowerShell script:

irm https://lazyskills.sh/install.ps1 | iex

And for people who already have Go, the module installs directly:

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

Then you launch it, with no arguments:

lazyskills

Running it from inside a project is the intended usage, because the tool scopes its view to the current directory. The left pane groups skills by source, so you can quickly see what came from the same repository, from a local folder, or from a custom install. That grouping is the TUI's first idea, and it is the right one: the source tells you how a skill arrived and therefore how you would update or remove it.

The keymap is short enough to learn in a minute, which is the point of a tool whose author describes themselves as too lazy to debug broken skills by hand. The slash key searches skills, the a key cycles through agent visibility filters, f toggles between project, global and all scopes, enter opens details for a skill or source, c shows the available actions, n finds new skills from skills.sh, space selects a skill for bulk actions, u reinstalls or updates the selected skill, x removes it, and the question mark shows the full keymap.

Two design decisions are worth calling out. The a key cycles agent visibility filters, which means checking whether a skill works in Claude Code versus Codex is a single keystroke rather than a directory comparison. And the TUI previews actions before running them, with destructive actions requiring confirmation.

Finding skills without leaving the terminal

Two features cover the discovery side, and one of them is usable without the TUI at all.

The first is the n key, which finds new skills from skills.sh, the same registry the install path refers to when it tells you to search skills.sh from inside LazySkills, preview the install command, and then install to project or global scope with confirmation. The preview step is what makes this usable: the point of the tool is that you see the command before it runs, so you can install a skill from a registry you did not write without pasting a shell command you have not read.

The second is a command-line find for agent-friendly registry search without opening the TUI:

lazyskills find --json "browser automation"

The --json flag is the detail that matters for a different audience. A skill inventory tool is most useful to a second kind of user, namely an agent, and a JSON output mode means an agent can ask the same question the TUI asks and parse the answer. The doctor command has the same property, which the README makes explicit by saying to use structured output in scripts or other agents.

That dual interface, a TUI for a person and JSON for a program, is a design choice worth noting in a category of tool that usually picks one. The TUI is for the human debugging a mess, and the JSON mode is for the agent that is part of the mess.

The TUI itself also has a discover more from a source feature, which scans local checkouts or GitHub skill sources to find skills you have not installed yet, so the tool is not limited to the public registry.

Doctor: a read-only health report, and what it will not do

The doctor command is the most immediately useful thing in the tool for someone with a broken setup.

Run it for the current project:

lazyskills doctor

It produces a read-only health report that ranks scan errors before warnings and shows the affected skill or workspace, the path, and a safe next step. For scripting, there is a JSON variant and a way to point it at another directory:

lazyskills doctor --json
lazyskills doctor --cwd /path/to/project

The important property is stated as a guarantee rather than a feature. Doctor never changes skills or lock files. It reports findings and points to commands such as lazyskills restore when a locked skill is missing from disk.

That is the right design for a diagnostic tool in a directory full of other people's files. A checker that fixes things while checking is hard to trust, because you cannot tell what it changed. Here the division is clean: doctor tells you what is wrong, and the separate restore command is the thing you run when you have decided to act.

The ranking of errors before warnings is also a considered choice. A report that lists forty warnings before the one error that explains your problem is a report you have to read rather than use, and putting the errors first means the first screen answers the question that matters.

The output naming conventions are consistent with the rest of the tool: the doctor command reports a skill or workspace, a path and a next step, and the next step is a command you can run.

Restore, and the race it narrows but does not close

Restore handles the case where a lock file records a skill that is no longer on disk. The scope flags are the three you would expect:

lazyskills restore --global
lazyskills restore --project
lazyskills restore --all

You can also name skills to restore only those entries, or pass --yes to accept the preview non-interactively:

lazyskills restore --project code-review tdd
lazyskills restore --global --yes

Without a scope flag, restore checks both scopes. And the behaviour between the preview and the execution is where the engineering is.

Before each install, restore rescans and revalidates that skill's lock identity and restore command. It then aborts without running the remaining commands if the skill disappeared, its lock metadata changed, or its command changed, and it reports any skills already restored.

The README is careful about the claim, and the caution is the most honest sentence in the documentation. That behaviour narrows races with concurrent installs; it does not make restore fully race-free.

That is worth reading as a design brief in miniature. The tool is a terminal UI that manages files other tools write to, and it has to survive the case where the state changes underneath it between the moment you look and the moment you act. Re-validating identity and command immediately before each install, rather than once at the start, means a skill that was swapped between preview and execution is caught. What is not covered is two restores running at the same time, and the documentation says so rather than implying a guarantee it cannot make.

For a user, the practical reading is that restore is safe to run and will not act on stale assumptions, and that the preview is worth reading rather than skipping with --yes when you are not sure what changed.

Updates, and the deliberately manual upgrade

The update story is a small one and the design choice is telling.

LazySkills can check for new releases and show the command to update your installation manually. The command is:

lazyskills update

It has two options. The --check flag queries whether a newer version is available and exits 0 if the status was checked cleanly, which is the flag a script would use. The --print-command flag prints the command required to upgrade on your channel, such as brew upgrade, and exits, so the tool never performs the upgrade itself.

The TUI does the same thing passively. When a newer version of LazySkills is available, an update notification appears in the TUI footer, and pressing U from the inventory view opens an update info modal showing the release details and the specific terminal command needed to upgrade manually.

So a tool that manages skills for Claude Code, OpenCode, Codex, Cursor and Gemini CLI deliberately does not update itself. It tells you the command and leaves you to run it, which is consistent with the rest of the design: the preview-before-acting rule, the confirmation on destructive actions, and the read-only doctor. A tool in the middle of your agent configuration is exactly the place where an unrequested self-modification would be unwelcome, and the author clearly reasons about that.

For the same reason, the TUI footer notification is quiet, a single line in the footer rather than a modal that interrupts, and the modal only appears when you press U.

How to evaluate it

The evaluation turns on whether you have the problem it solves.

If you use one or two agents and have a handful of skills that work, this tool is overhead. The inventory view is most valuable when skills are spread across scopes and agents, when installs have accumulated, or when something stopped being visible and you need to know why.

If you are in that situation, the order of use is sensible. Start with doctor, because it is read-only and will tell you what is actually broken. Then use the TUI with the agent visibility filter cycled through the agents you use, which is the fastest way to find the scope mismatch that causes most of the confusion. Then use the actions, which preview before they run.

Two things to check before installing it. The first is Go version, because the module requires 1.26.3, which is a recent floor. The second is the Go dependency stack, because the go.mod shows the terminal UI is built on the Charm libraries, bubbletea, bubbles, lipgloss and glamour, with a fairly deep indirect dependency list beneath them. That is a normal price for a polished terminal interface in Go, but it is a dependency footprint, and the install script route means you would be running a binary you did not compile.

The scope of what it touches is also worth noting. It reads and writes skill directories and lock files, it can run install and update commands on your behalf with a preview, and it can remove skills. The confirmation prompts and the read-only doctor are the mitigations, and they are deliberate ones, but the tool is a privileged helper in your configuration directories and it is worth running the read-only commands first.

The agent-facing JSON output is the differentiator that would matter in a team. A skill inventory that an agent can query, and a doctor that an agent can run, is closer to infrastructure than to a utility, and that is a reasonable reason to adopt it even if the TUI itself is only for the one person who maintains the skills.

Editorial conclusion

Adopt lazyskills if you run more than one coding agent, keep skills across project and global scopes, and have lost track of which agent can actually see which skill, because the visibility filter and the read-only doctor are the two features that turn guesswork into a listing. Do not adopt it expecting it to update itself, since the tool deliberately prints the upgrade command instead of running it, and do not run its write actions without reading the preview, because it removes and reinstalls files in your agent configuration directories. Before you commit, run lazyskills doctor in a project and read the report, check that your Go toolchain is at 1.26.3 or that you are comfortable with the install script binary, and cycle the agent visibility filter across every agent you use to find the scope mismatches first.

Frequently asked questions

Official sources

1. alvinunreal/lazyskills on GitHub
2. License: MIT
3. Project website
4. README
5. Releases