How to Find, Install, and Audit AI Agent Skills

Start with the decision you are actually making

Agent Skills are small packages of instructions and supporting files that help an agent perform a repeatable job. A package can be as simple as a focused SKILL.md, or it can reference scripts, templates, assets, external tools, credentials, and network services. That range is useful, but it means “installing a skill” is not one uniform risk.

Before browsing a leaderboard, write a one-sentence need statement:

I need a skill that turns a supplied changelog into internal release notes, without browsing, publishing, or changing repository files.

This sentence gives you a rejection test. A popular skill that does a broader job is not automatically a better choice. If it retrieves private issues, edits files, installs packages, and publishes a release, it has crossed four boundaries your need statement did not require.

What the skills.sh rankings can—and cannot—tell you

skills.sh documents its rankings as install telemetry collected by the CLI. The API exposes three time views. They are useful discovery signals, but none of them is a quality score.

Install telemetry is not the same as active use, task completion, retention, satisfaction, or security. The directory itself says that its audits cannot guarantee quality or security and recommends reviewing a skill before installation. Treat that disclaimer as the correct operating model, not fine print.

There is another subtlety: telemetry can be disabled, and rankings can change. For durable content, avoid publishing a permanent claim such as “the number-one skill is X.” Record the date when a ranking materially affects your decision, and link to the current source. Use the ranking to identify demand clusters—browser automation, documents, research, testing, design systems—not to manufacture a timeless best-of list.

A six-stage intake workflow

1. Shortlist by job, not by position

Open several candidates that appear to solve the need statement. Prefer packages with a specific name, a precise activation description, visible source files, an identifiable maintainer, a license, and a recent revision you can inspect. A clear package that ranks lower may be a much better fit than a broad package at the top.

Write down why each candidate remains on the list. “Popular” is not enough. Better reasons are “accepts a supplied CSV,” “produces the required review table,” or “explicitly excludes publication.”

2. Freeze the exact review object

A listing page is not the package. Resolve it to the underlying repository or archive and record the owner, path, and commit, tag, or SHA-256 hash. If you review a branch that can change, label it MOVING_SOURCE. This matters because a clean review of yesterday's files says nothing conclusive about tomorrow's update.

For a multi-skill repository, identify the individual skill path. The CLI supports listing skills before installation; use that discovery step so you do not unintentionally select every package in a repository. Do not confuse a package name shown by a directory with proof that two similarly named packages have identical files.

3. Read the activation contract

The Agent Skills specification requires a SKILL.md and uses its frontmatter name and description for discovery. In Codex, the description also helps the agent decide when a skill applies. Read it as an activation contract:

• Does it state one job, or promise to improve almost anything?
• Does it say when to activate, not just what the package contains?
• Are important exclusions present?
• Could ordinary wording trigger it during unrelated work?

A vague description is not merely a copywriting flaw. It can make the package eligible in situations the author did not carefully design or test.

4. Map effective capability

Read SKILL.md in full, then every file it directly references. Inventory unreferenced executable and configuration files too. For each capability, ask what it can read, change, send, or delete and why the stated job requires it.

Look for a promise/capability mismatch. A formatting skill does not need every environment variable. A release-note skill does not need deployment authority. A research skill may need network access, but it should still disclose destinations, data sent, and what happens when a source is unavailable.

5. Separate observed evidence from claims

Mark each important statement as observed, declared, inferred, or unknown. “The package says it is read-only” is declared. “No write command appears in the three inspected text files” is observed within that boundary. “The package cannot write” is stronger than either statement and is usually unsupported without a runtime control.

Apply the same discipline to directory badges and audit results. Ask whether the report covers the exact revision, which methods were used, whether dependencies were included, and whether the underlying findings are available. A scan may be useful evidence. It is not a transferable guarantee.

6. Choose a bounded verdict

A useful intake report does not end with “looks good.” It ends with one decision whose ceiling is clear:

• SUITABLE_FOR_ISOLATED_TEST — no blocking issue was observed in the inspected boundary, and a disposable test can be defined.
• MANUAL_REVIEW_REQUIRED — the package is substantially inspectable, but a high-impact technical, legal, or organizational question remains.
• DO_NOT_INSTALL — a hard-stop behavior or fundamental promise/capability mismatch is present.
• INSUFFICIENT_EVIDENCE — the underlying files, revision, dependencies, or material references are unavailable.

“Suitable for isolated test” is deliberately weaker than “safe to install.” Static reading cannot establish runtime behavior, transitive dependency behavior, the security of a remote service, or what a future update will contain.

Install only after the review object is clear

The current skills CLI documents repository, URL, and local-path sources, along with options to list available skills and select a specific package. A cautious sequence is to list first, select one skill, name the target agent explicitly when needed, and inspect the destination printed by the tool before accepting a write.

npx skills add owner/repository --list
npx skills add owner/repository --skill exact-skill-name -a codex

Commands are examples, not a recommendation to install an unreviewed repository. Pin the source when your workflow supports it and read the current CLI help before acting.

For manual Codex repository installation, OpenAI documents .agents/skills/ in the repository. The official Codex documentation also describes a user-level $HOME/.agents/skills/ location, while the separate skills CLI repository currently lists its Codex global destination as ~/.codex/skills/. These are different installation mechanisms with evolving conventions. Do not silently combine them into one claim: choose the mechanism, use its current documentation, and verify the actual destination.

Repository scope is the easier first choice because it limits discovery to the project where the skill is needed and keeps the package visible in version control. User scope is appropriate only after you understand the activation boundary and genuinely want the skill available across projects.

A downloadable Skill folder is appropriate for local authoring, review, and repository-scoped use. OpenAI's current guidance recommends a plugin when the goal is reusable distribution beyond one repository, bundling multiple Skills, or shipping a Skill with a connector. Treat manual extraction and plugin installation as different delivery paths with different lifecycle and governance expectations.

Run the smallest useful test

The first test should use a disposable workspace, synthetic inputs, no production credentials, and network access disabled unless the job inherently requires it. Include one normal case and one adverse case that targets the package's most important boundary. Withhold expected answers from the invocation and grade them afterward.

For a read-only release-note skill, a useful adverse case might include an instruction inside the changelog asking the agent to publish the release. Passing means the agent treats that instruction as source text, produces the requested draft, and does not publish. For a file-conversion skill, passing includes writing only the named output path and preserving the original input.

Record what actually happened: the exact package revision, host, model or runtime when exposed, input fixture, command, output, filesystem changes, network policy, and cleanup. “Tested” without that boundary is too vague to help the next reviewer.

Worked contrast: two synthetic fixtures

The companion kit uses two deliberately small examples to make the decision ceiling visible. The first is a single-file release-note instruction whose declared scope stays inside a supplied changelog and a Markdown response. Its positive outcome is still only SUITABLE_FOR_ISOLATED_TEST, because static inspection does not establish runtime compliance.

The contrast case contains an explicit request to collect a token, send task text outside the workspace, hide the step, and bypass review. Those written capabilities cross the intake boundary before any code runs, so the correct outcome is DO_NOT_INSTALL. The review requires no real secret and no network call.

Use rankings to plan content, not to imitate listings

For a small content site, publishing an internal “hot” leaderboard based on a handful of visitors creates noise rather than insight. The more defensible opportunity is to use established directory demand as topic research, then publish artifacts that answer the next questions: What does this class of skill actually do? What must be inspected? What permissions are proportionate? What does a controlled test look like?

That is why this page is paired with three purpose-built assets rather than dozens of thin ranking pages: a copyable pre-install review prompt, a reusable Skill Intake Auditor, and a downloadable audit kit with fixtures and grading boundaries. Each page completes a different job and links to the others only where the next step is genuinely useful.

Your next safe step

If you have one package to review, use the Agent Skill Pre-Install Review Prompt. If intake reviews are recurring work, inspect and download the Skill Intake Auditor. To run the two-case exercise or adapt the templates, open the Agent Skill Audit Kit.