Install Agent Skills in Codex, Claude Code, Cursor, and Gemini CLI

Teams that need to install agent skills across more than one coding tool should start by choosing one trusted skill, a project or personal scope, and a platform-specific verification step. This guide keeps Codex, Claude Code, Cursor, and Gemini CLI installation paths separate so one client’s command is never treated as a universal setup.

Tool Summary

Agent Skills are portable folders whose required entry point is SKILL.md; they can also contain scripts, references, and assets. The shared format does not make every client’s installer, scope directory, reload behavior, or permission model identical. Start with a known repository and one named skill, then use the platform’s own discovery surface to confirm it is available.

Best Fit Users

• Individual developers: want a personal skill available in several local projects without copying it blindly into every repository.
• Repository maintainers: need a project-scoped skill that can be reviewed, versioned, and shared with the team.
• Workspace admins: need to distinguish an approved skill folder from permission grants, shell access, or any bundled external integration.

Setup / Working Method

1. Review before installing

Read the skill’s frontmatter, instructions, bundled scripts, referenced files, and declared tool assumptions. A skill can guide an agent toward commands or data access; installation is not permission to run every suggested action.

2. Install one skill with the Vercel Skills CLI

Use this manager when you want an explicit target. It can target named agents and defaults to project scope. Replace the repository and skill name with the reviewed source; do not omit the target when several agents are installed.

npx skills add vercel-labs/agent-skills --skill web-design-guidelines --agent codex -y

Use -g only when you deliberately want a personal installation; use npx skills add owner/repo --list before selecting an unfamiliar skill. The CLI also supports npx skills list, npx skills update, and npx skills remove; scope and agent flags must still match the installation you are managing.

3. Codex: separate project and personal scope

• Project path: .agents/skills/skill-name/SKILL.md
• Personal path: $CODEX_HOME/skills/skill-name/SKILL.md (normally ~/.codex/skills/)
• Verify: start a fresh task or inspect the available-skills list after adding the folder.

Do not assume a running conversation has reloaded a newly created folder. The CLI target --agent codex applies only when Codex is the chosen installer target.

4. Claude Code: add the folder, then check discovery

• Project path: .claude/skills/skill-name/SKILL.md
• Personal path: ~/.claude/skills/skill-name/SKILL.md
• Verify: give Claude a matching task or invoke the named skill from the slash menu.

Claude Code watches existing skill directories. If the top-level skills directory did not exist when the session started, restart so it can be watched.

5. Cursor: confirm the selected skill surface

• Repository path: .cursor/skills/skill-name/SKILL.md, or .agents/skills/ when that is the team’s portable project convention.
• Personal path: ~/.cursor/skills/skill-name/SKILL.md
• Verify: confirm the skill appears in the Skills or slash-command surface before relying on it in an agent run.

Use --agent cursor only when the Skills CLI is the chosen installer; it is not a universal Cursor command.

6. Gemini CLI

Gemini CLI provides its own installer for a reviewed remote source:

gemini skills install https://github.com/vercel-labs/agent-skills

Use workspace .gemini/skills/skill-name/SKILL.md or user ~/.gemini/skills/skill-name/SKILL.md when you manage the folder directly. In Gemini CLI, verify discovery with /skills list; use /skills reload after changing folders, and disable the named skill before removing a copy you may want to restore.

Comparison / Limits

• Shared format, different lifecycle: all four can consume SKILL.md-based skills, but their discovery, scope precedence, and reload behavior differ.
• Project scope first: use a repository folder when the skill is part of a team workflow and should be code-reviewed. Use global scope only for a personal, reusable workflow that does not encode repository-specific rules.
• One named skill first: install or copy one reviewed skill before using an “all skills” option. Broad bundles expand the audit surface and may pull in scripts or references your task does not need.
• Update and removal are scope-bound: update with the same manager or source checkout that installed the skill. Remove only the matching project or global copy; disabling in Gemini CLI is reversible, while deleting a directory is not.

Common Mistakes & Fixes

• Using a Claude Code path for Codex or Cursor: choose the client-specific directory or an explicitly targeted Skills CLI install, then verify in that client.
• Installing globally by accident: omit -g unless you intend a personal installation; project scope is easier to review and remove with the repository.
• Trusting a skill because it has a familiar name: inspect SKILL.md, supporting files, shell snippets, and links before enabling it.

Use Cases

• Team code-review checklist: commit one project skill, review it through normal pull requests, and confirm each developer’s client discovers it.
• Personal repeatable workflow: install one named skill globally for the one client you use most, then test a harmless task before adding other agents.
• Cross-tool evaluation: install the same reviewed skill separately in Codex, Claude Code, Cursor, and Gemini CLI, recording each client’s scope and verification result rather than copying a command between them.

FAQ

• Q: How do I install agent skills safely?
  A: Start with one trusted source, inspect its instructions and scripts, choose project scope by default, and use the destination client’s discovery command or UI to verify it loaded.
• Q: Can I use one Skills CLI command for every client?
  A: No. The manager can target multiple supported agents, but the target flag and each client’s own skill directory or reload behavior remain platform-specific.
• Q: Should a team use project or global scope?
  A: Usually project scope. It keeps the skill visible in version control and lets reviewers evaluate changes with the codebase.
• Q: What should I do before updating or deleting a skill?
  A: List installed skills, identify the original scope and manager, review the update diff where possible, and disable or remove only that matching installation.

Follow @bigprompt, share your trusted-skill review checklist in the comments, and explore AI Tools with Coding & Development.

Related Big Prompt Hub pages

AI tools for selecting practical agent workflows safely

Coding and development resources for controlled local work

Prompt engineering guides for reusable team operating instructions

AI workflow prompts for repeatable review and delivery

Business productivity practices for safer team automation

Before enabling a candidate, review a skill before installation.

After adoption, audit unused skills after adoption.

Big Prompt Hub Review

The useful default is not to install every available skill. Start with one project-scoped, reviewed folder and prove that the named client discovers it. The shared format helps portability, but trustworthy operation comes from preserving each platform’s own path, scope, reload, and permission boundaries.