skills.sh agent skills directory: install, write and vet

Third-party skills for Claude Code, Codex and other coding agents raise two questions: which to add, and what a team lead should let developers install. The guide explains what skills.sh is, how Agent Skills work across agents, how to install one, how to write a minimal one, and how to check a skill before it runs on your machine.

As a cloud infrastructure and security engineer, I treat a skill the way I treat a dependency that can reach a shell: useful, and untrusted until read. The facts below were checked against the official sites and repositories in November 2026.

What skills.sh is

skills.sh calls itself “The Agent Skills Directory”, and the footer says it is made by Vercel. It is the public face of an open-source command-line tool, vercel-labs/skills, published on npm as skills under the MIT licence. The CLI needs Node.js 22.20 or later, and its README says it supports OpenCode, Claude Code, Codex, Cursor “and 75 more” agents.

Three things are easy to get wrong about it:

• It is a directory, not a host. Skills live in Git repositories, mostly on GitHub. You install by naming owner/repo, and the CLI fetches from there.
• The leaderboard measures installs, not quality. Rankings come from anonymous telemetry sent by the CLI, which the docs say “only tracks which skills are being installed”.
• It does not vouch for what it lists. The docs state plainly: “we cannot guarantee the quality or security of every skill listed on skills.sh.”

Since February 2026 every listed skill also gets automated security audits from three partners: Gen Agent Trust Hub, Socket and Snyk. Results appear on each skill’s page and together at skills.sh/audits. Skills flagged as malicious are hidden from the leaderboard and search, a warning appears if you open one directly, and from [email protected] the CLI shows audit results and risk levels before it installs anything.

One trade-off to know about: setting DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 turns off the CLI’s telemetry and its security-audit requests together.

How Agent Skills work

Agent Skills are an open format documented at agentskills.io. A skill is a directory with one required file:

pr-summary/
├── SKILL.md        # required: frontmatter plus instructions
├── scripts/        # optional: code the agent can run
├── references/     # optional: docs loaded when needed
└── assets/         # optional: templates, schemas, data

SKILL.md starts with YAML frontmatter. The specification requires two fields:

Field	Rules
name	1 to 64 characters: lowercase letters, digits and hyphens. No leading, trailing or double hyphens. Must match the directory name.
description	1 to 1,024 characters. Says what the skill does and when to use it.

Optional fields are license, compatibility (up to 500 characters), metadata (string key-value pairs) and allowed-tools, which the spec marks as experimental.

The format is built on progressive disclosure. At startup the agent loads only each skill’s name and description, roughly 100 tokens per skill. When a task matches a description, it loads the full body; the spec recommends keeping that under 5,000 tokens and under 500 lines. Files in scripts/, references/ and assets/ load only when the instructions call for them. The practical consequence: the description is the trigger. A vague description means the skill never fires, or fires when it should not.

In Claude Code

Claude Code follows the standard and adds its own fields.

Location	Path	Scope
Personal	~/.claude/skills/<name>/SKILL.md	All your projects on this machine
Project	.claude/skills/<name>/SKILL.md	This repository; commit it to share
Plugin	<plugin>/skills/<name>/SKILL.md	Wherever the plugin is enabled, as /plugin-name:skill-name

Enterprise skills beat personal ones, and personal beat project. Claude uses a skill when the task matches its description, and you can also call it directly as /skill-name. Claude Code-only frontmatter includes disable-model-invocation: true, which means only you can trigger the skill, user-invocable: false for skills only Claude should call, allowed-tools to pre-approve tools for the turn, and context: fork to run the skill in a subagent. Two details catch people out: Claude Code ignores unrecognised fields without an error, and the combined description and when_to_use text is cut off at 1,536 characters in the skill listing.

In Codex

Codex scans .agents/skills in every directory from your working directory up to the repository root. It also reads $HOME/.agents/skills for your own skills and /etc/codex/skills for machine-wide ones. It also ships system skills, including skill-creator and skill-installer. You invoke a skill with /skills or by typing $ and its name, and Codex can also pick one when the task matches the description.

An optional agents/openai.yaml sets UI metadata, tool dependencies and the invocation policy; allow_implicit_invocation: false limits a skill to explicit calls. To switch a skill off without deleting it, add this to ~/.codex/config.toml and restart Codex:

[[skills.config]]
name = "pr-summary"
enabled = false

Everywhere else

The same SKILL.md works across agents. What changes is the folder each agent reads. A few from the skills CLI’s agent table:

Agent	Project path	Global path
Claude Code	.claude/skills/	~/.claude/skills/
Codex	.agents/skills/	~/.agents/skills/
Cursor	.agents/skills/	~/.cursor/skills/
Gemini CLI	.agents/skills/	~/.gemini/skills/
GitHub Copilot	.agents/skills/	~/.copilot/skills/
OpenCode	.agents/skills/	~/.config/opencode/skills/

If you split work between agents, the Claude Code vs Codex CLI comparison covers where each one fits.

Install a skill with the skills CLI

Run these from your project. Look first, then install narrowly:

# See what a repository offers without installing anything
npx skills add vercel-labs/agent-skills --list

# Install one named skill, for one agent, in this project
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code

# Pin a release tag (a full commit also works)
npx skills add owner/[email protected] --skill my-skill

Installs go to the current project by default; -g installs globally. In interactive mode you choose between a symlink, which the docs recommend, and --copy. With a symlink the CLI keeps one copy under .agents/skills/<name> and links each agent’s folder to it, so Claude Code and Codex share the same files.

The CLI records project installs in skills-lock.json, including a SHA-256 content hash of each skill’s files. That turns the lock file into a tamper check:

npx skills list     # flags skills whose files no longer match the lock as "modified"
npx skills check    # reports updates and local changes; exits 1 if there are any
npx skills update   # updates installed skills
npx skills remove   # removes them

Because npx skills check exits with code 1 on updates or local changes, it can gate CI. Two more commands are useful: npx skills find searches the directory, and npx skills use owner/repo@skill --agent claude-code tries a skill from a temporary directory without installing it.

Avoid --all and -y on any source you have not read. They install every skill to every agent and skip the prompts that would have shown you what was coming.

Write a minimal skill

npx skills init pr-summary creates a template. A useful skill does not need much more than this:

---
name: pr-summary
description: Writes a pull request description from the current branch's commits and diff. Use when the user asks for a PR description, PR summary or change summary for a branch.
---

# PR summary

1. Run `git log --oneline origin/main..HEAD` and `git diff --stat origin/main...HEAD`.
2. Read only the changed files needed to explain the change.
3. Write a title of at most 72 characters, a "What changed" list, a short "Why" paragraph and a "How to test" list.
4. Do not invent ticket numbers, metrics or reviewers. If the reason for a change is not in the commits or diff, ask.

Put the folder in .claude/skills/ for Claude Code, .agents/skills/ for Codex, or install it into both with npx skills add ./path-to-your-skills. Then ask the agent to “write a PR description for this branch” and check that the skill is picked up. If it is not, the description is usually the problem: lead with the task words people actually type.

A few habits keep skills small and predictable:

• Prefer instructions to scripts. OpenAI’s Codex guide recommends scripts only when you need deterministic behaviour or external tooling. Every script is code someone has to review.
• Make side effects explicit. For anything that deploys, sends or deletes, add disable-model-invocation: true in Claude Code, or allow_implicit_invocation: false in Codex, so it runs only when a person asks.
• Validate the format. The spec’s reference library provides skills-ref validate ./pr-summary to check frontmatter and naming.
• Move bulk into references/. Keep SKILL.md short, and keep file references one level deep.

Vet third-party skills before you install them

A skill is instructions plus optional code, and both run with your agent’s permissions. Claude Code’s documentation warns that “a skill can grant itself broad tool access, so review the allowed-tools of skills checked into a repository before you run Claude Code there”, and that it applies a project skill’s allowed-tools even in a -p run in a folder you have never trusted.

The directory’s audits help, but they are not a gate. In June 2026 Trail of Bits published “The sorry state of skill distribution”. They built four malicious skills and got them past ClawHub’s detector, Cisco’s skill scanner and all three scanners integrated into skills.sh. Three of the four took less than an hour to build. The techniques are worth knowing because they show where to look:

• A SKILL.md that sends the agent to a .docx file, which is a ZIP archive carrying a malicious script.
• Precompiled Python bytecode (.pyc) that did not match the readable source and read environment variables.
• A prompt injection that presented a switch of npm and yarn registries to an attacker-controllable domain as corporate configuration.
• Against ClawHub, 100,000 newlines in front of the payload, so the scanner truncated the file before reaching it.

Their conclusion was blunt: they “strongly discourage the use of skills.sh, ClawHub, and similar marketplaces” for sensitive work, and recommend curated collections, version pinning and control over who can add or update skills. A High Risk flag on skills.sh is worth acting on. A clean result tells you much less.

Here is the review I would run before any third-party skill goes near a client repository.

1. Check the publisher. Confirm the repository belongs to the organisation it claims to, and look at its age, maintainers and open issues. Install counts measure popularity, not review.

2. Read every file, not only SKILL.md. Clone it somewhere disposable and list everything, including hidden files:

dir="$(mktemp -d)"
git clone --depth 1 https://github.com/OWNER/REPO "$dir"
cd "$dir"
# every file, hidden ones included
find . -type f -not -path './.git/*' | sort
# anything that is not plain text: binaries, archives, .pyc, office documents
find . -type f -not -path './.git/*' -exec file {} + | grep -v -i 'text'
# unusually large files, where padding can hide a payload
find . -type f -not -path './.git/*' -size +200k

3. Search for red flags, then read each hit in context:

grep -rniE 'curl|wget|https?://|base64|eval|\.env|\.ssh|\.aws|token|secret|registry|npmrc|yarnrc|sudo|rm -rf' .
grep -rnE 'allowed-tools|disable-model-invocation|!`' --include=SKILL.md .

Look for network calls to unknown hosts, reads of environment variables or credential files, changes to package registry settings, writes outside the project, instructions to skip confirmation or hide output, broad allowed-tools grants, and Claude Code’s !`command` syntax, which runs a shell command when the skill is invoked.

4. Pin and lock. Install from a tag or commit, commit skills-lock.json, run npx skills check in CI, and read the diff before every npx skills update.

5. Install narrowly. Project scope, one agent, named skills. Keep permission prompts and sandboxing on while you try a new skill, and never try one in a bypass-permissions session.

6. Curate for teams. Keep reviewed skills in an internal repository or plugin marketplace and install from there. Trail of Bits publishes one example, trailofbits/skills-curated. To switch off a skill without deleting it, use [[skills.config]] in Codex, or the skillOverrides setting with "off" for personal and project skills in Claude Code.

For a broader process covering plugins, MCP servers and hooks as well as skills, see the guide to security review skills for AI coding agents. If you use the ECC plugin, its catalogue is covered in the Everything Claude Code guide.

Before you install a skill

• skills.sh is Vercel’s directory for Agent Skills; the skills CLI from vercel-labs/skills installs them into Claude Code, Codex and many other agents.
• A skill is a folder with SKILL.md. The required name and description load at startup, and the description decides when the skill fires.
• Claude Code reads .claude/skills/; Codex reads .agents/skills/. The CLI can link one copy into both.
• Install with --list first, then --skill and -a for one agent, pinned to a tag or commit, with skills-lock.json committed.
• Read every file before installing, including binaries, archives and hidden files. Treat audits as a signal and curation as the control.