How to Install and Verify an Agent Skill
Install one agent skill with the Skills CLI, choose the right scope, check discovery, and troubleshoot dependencies before using real project files.
Source reviewed · SkillDex editorial
Installing an agent skill is a small change to your development environment, but there are three different outcomes to check. The files must arrive in the intended location, your chosen agent must discover the instructions, and the workflow must work with the tools available on your machine. A successful installation message establishes only the first part.
This guide describes a repeatable first-install process. Commands are examples based on the upstream documentation reviewed on November 17, 2026; they are not a claim that SkillDex executed this workflow in every supported client. Start with one specific skill and a disposable project so you can understand the change before sharing it with a team.
Define the task before choosing a package
Write a one-sentence task and a clear output. “Review the keyboard navigation of this checkout form and return file-and-line findings” is more useful than “make my project better.” The narrower task makes it easier to decide whether a candidate adds relevant instructions or just more material for the agent to interpret.
Open the candidate’s original repository and its SKILL.md. Confirm the publisher, the exact skill name, bundled scripts, and any tool requirements. A repository can contain many skills. The repository name, directory name, displayed title, and name used by an installation selector are not necessarily interchangeable. Use the listing command before guessing.
For a discovery workflow, read our Find Skills entry. Discovery is a way to find candidates; it does not approve everything a search returns.
Check the installer and its scope
The current Skills CLI README requires Node.js 22.20 or later. Check the terminal you will actually use, because different terminals can resolve different Node installations.
node --version
npx skills --help
Running npx may download the CLI package when it is not already available. Read the package prompt and use the expected package. If your organization pins tool versions or controls package registries, follow that setup instead of changing it just to match a tutorial.
Choose a project directory before installing. The CLI defaults to project scope; global scope uses the additional -g option. For a first evaluation, project scope keeps the instructions associated with one experiment and makes the resulting file changes easier to review. A global install is useful when you intentionally want the same workflow available across unrelated projects.
If the project is already under Git, inspect its status before you start. That gives you a baseline for recognizing new skill folders, links, and lock-file changes afterward. Preserve unrelated work rather than resetting the entire project to undo an installation.
List first, then select one skill
The upstream command reference documents listing without installing and selecting by skill and agent. For example:
npx skills add vercel-labs/agent-skills --list
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code
The first command lets you check that the intended skill is discoverable in the repository. The second limits the install to that named skill and Claude Code. Keep the interactive prompts for your first attempt so you can inspect the scope and destination. Avoid choosing every skill and every agent merely because the installer offers that shortcut.
For another supported client, use its documented agent identifier. In particular, the Skills CLI identifier for Gemini CLI is gemini-cli; SkillDex’s shorter Gemini category label is not a command-line flag. The upstream agents table is the reference for the installed CLI’s target names and paths.
When reproducibility matters, the command reference also supports Git release tags or full commits. Record the version you chose and why. A human-readable “reviewed on” date tells you when someone checked the source, while a commit identifies the source contents more precisely.
Confirm what changed on disk
Run the listing command in the same project:
npx skills list
Inspect the installed skill’s SKILL.md and supporting resources. If installation used symbolic links, check that the target exists and that the terminal and client can both access it. Copy-based installation is an available alternative when the environment cannot support the links you need.
Current CLI documentation lists Claude Code’s project location as .claude/skills. Codex, Cursor, and Gemini CLI use the shared .agents/skills project location in the CLI’s target table. Global locations differ. Treat those as installer destinations, not a promise that every old client release or every managed workspace uses identical discovery behavior.
Do not stop at “the directory exists.” A partially copied skill may lack referenced scripts or templates. Open at least one referenced file and confirm that its relative path resolves from the installed skill directory.
Check discovery inside your client
Use the client’s own current documentation for discovery and invocation: Claude Code, Codex, Cursor, or Gemini CLI. Clients differ in refresh behavior, manual invocation, configuration, and supported frontmatter features.
Keep the first request small enough that you can tell whether the workflow was used. For the design-review example, ask for findings about one component rather than a rewrite of the entire application. Review the agent’s explanation and changed files. A claim that it loaded a skill is useful context, but the actual output still needs inspection.
If the client cannot find the skill, check project versus global scope, exact skill name, client version, discovery location, and required reload behavior. Installing the same skill repeatedly without checking these details can create confusing duplicate copies.
Separate dependency failures from discovery failures
A client may correctly load a skill and then fail because Python, a browser, an office renderer, or a command-line utility is missing. That is a runtime prerequisite problem, not necessarily an installation failure.
Read the relevant upstream requirements and install only the dependencies needed for the task you are evaluating. For document work, use copies of input files and choose a new output filename. Record the operating system, client version, missing command, and full error message so the problem can be reproduced.
Our document workflow guide explains why a generated file, a recalculated workbook, and a visually checked deliverable are different checkpoints.
Update or remove deliberately
The CLI provides separate commands for checking updates, applying them, and removing installed skills:
npx skills check
npx skills update web-design-guidelines
npx skills remove web-design-guidelines
Review upstream changes before updating a workflow used for important work. Repeat your small evaluation task after an update instead of assuming that an earlier result applies to the new version.
Removal needs the correct scope. A global installation requires the corresponding global removal option; removing a project copy does not necessarily remove another global copy. Check the CLI listing and client discovery again afterward. Removing instructions also does not reverse files the agent previously edited or uninstall every external dependency.
Keep a short evaluation record: source, version, installation scope, client, task, observed result, and unresolved limitations. That record makes the next decision practical: retain the skill, adjust the environment, or choose a better-matched alternative.