How to Audit an Agent Skill Before You Install It

Treat an Agent Skill like code, not like documentation. Before you install or enable one, inspect the exact immutable revision outside your privileged agent, read every referenced file and script, map its filesystem, credential, network, and dependency access, then test it in a disposable environment with no production secrets.

That sequence catches risks a reputation badge or automated scanner can miss. It also gives you a record of what you approved before the skill changes.

Why a SKILL.md file needs a security review

An Agent Skill is more than a prompt. The open Agent Skills specification allows a skill directory to contain instructions, reference files, assets, and executable scripts. OpenAI and Anthropic both document skills with optional scripts, and Anthropic notes that those scripts run in the agent's execution environment.

The practical risk is therefore a combination of:

• Instructions that influence what the agent reads, writes, downloads, or sends

• Scripts that execute with the agent's local permissions

• Referenced files that are not visible in the first screen of SKILL.md

• Package installers and nested dependencies that can run their own code

• Automatic skill matching that may load instructions when you did not explicitly name the skill

This is not a theoretical edge case. A 2026 study of 98,380 skills reported 157 confirmed malicious skills and 632 vulnerabilities across 13 attack techniques. Those counts do not mean every third-party skill is unsafe. They do mean that "it is only Markdown" is not a useful trust model.

Prerequisites

You need:

• A browser or terminal for reviewing the source

• Git, if the skill is hosted in a Git repository

• A disposable test directory, container, or virtual machine

• No production credentials, SSH keys, browser profiles, or customer data in the test environment

Do not ask the same highly privileged agent to install an untrusted skill and decide whether its instructions are safe. Review the raw files first, or use a separate read-only reviewer that cannot execute the skill.

Step 1: Resolve the publisher and exact revision

Start with provenance:

1. Who controls the repository and release process?

2. Does the publisher link to the skill from an official domain?

3. Is the version a commit hash or another immutable identifier?

4. Does the repository show unexplained ownership changes, binary additions, or recent rewrites?

Record the exact commit before reading files:

git clone --filter=blob:none --no-checkout --depth 1 https://github.com/OWNER/REPO.git skill-review
cd skill-review
git rev-parse HEAD

Cloning with --no-checkout lets you inspect the Git objects without populating a working tree. Do not initialize submodules, install packages, or run setup commands during this stage.

A branch name such as main is not a security pin because the publisher can move it later. Keep the reviewed commit hash with your approval record.

Step 2: Inventory every file before opening the skill

List the repository tree from the recorded commit:

git ls-tree -r --name-only HEAD

Find the target SKILL.md, then note every sibling script, reference, asset, configuration file, lockfile, and submodule declaration. A short top-level skill can delegate its important behavior to another file, so the review boundary is the full dependency graph, not one Markdown file.

Read files directly from the commit without checking them out:

git show HEAD:path/to/SKILL.md
git show HEAD:path/to/referenced-file.md
git show HEAD:path/to/script.sh

If SKILL.md points to a URL, package, executable, template, or another repository, add that target to the inventory. If you cannot resolve a required dependency to an inspectable version, stop the review.

Step 3: Trace instructions and executable behavior

Read the skill as an execution plan. For each instruction, write down:

• What triggers it

• Which command, tool, or dependency it invokes

• Which files or environment variables it can read

• Which files, settings, or remote systems it can change

• Which network destinations receive data

• What success looks like and how the result is verified

Use a text search to surface review hotspots:

git grep -n -E 'curl|wget|Invoke-WebRequest|base64|eval|exec|subprocess|child_process|os\.system|rm -rf|sudo|chmod|\.ssh|\.env|TOKEN|SECRET|PASSWORD' HEAD -- path/to/skill

A match is a prompt for investigation, not proof of malicious behavior. A clean result is not proof of safety either. Obfuscated code, indirect imports, downloaded scripts, and ordinary-looking instructions can still create risk.

Pay special attention to instructions that:

• Override prior safety rules or tell the agent to hide actions

• Read broad directories instead of named files

• Upload context, logs, source code, or credentials

• Execute downloaded code without verifying a digest

• Install packages whose versions are not pinned

• Change shell profiles, agent instructions, hooks, or startup files

• Delete data or rewrite Git history

• Ask for administrator, root, browser, wallet, or production access

Step 4: Build a permission and dependency map

Use one row for each capability the skill needs:

Reject a skill whose requested access is materially broader than its job. A formatter should not need browser cookies. A documentation helper should not need deployment credentials. A read-only catalog search should not write to your repository.

Step 5: Decide whether to reject, revise, or sandbox

Use three outcomes:

Reject

Reject the skill when its source or dependencies cannot be inspected, its publisher cannot be resolved, it hides or obfuscates behavior, it requests unrelated privileges, or it asks the agent to bypass user review.

Revise

Revise or fork the skill when the purpose is useful but the access is too broad. Remove unused scripts, pin dependencies, replace broad directory reads with named paths, and separate read-only discovery from mutations. Review the resulting commit as a new artifact.

Sandbox

Sandbox the skill only when the remaining risk is understood and the test environment can contain it. Sandboxing is not a substitute for source review; it limits the damage of behavior you may have missed.

Step 6: Run a disposable, least-privilege test

Create a fresh environment from the reviewed commit. Give it only synthetic inputs and the minimum access needed for one expected path:

1. Disable or restrict network access unless the skill's purpose requires it.

2. Mount only the test directory, preferably read-only at first.

3. Leave production secrets, SSH agents, cloud credentials, browser profiles, and personal files outside the environment.

4. Run the smallest documented example.

5. Record processes, network requests, and filesystem changes.

6. Compare the result with the skill's stated output and run its independent verifier.

7. Delete the environment after preserving the review record.

The expected result is narrow: the skill completes its stated example, touches only approved resources, and produces the documented output. Unexpected network traffic, writes outside the test directory, new persistence, or requests for more privilege are failures.

Common audit failures

Reviewing only SKILL.md

Referenced scripts and files are part of the skill. Follow every link and import before approval.

Trusting an automated scanner as the decision

Scanners are useful for triage, but they cannot prove that a workflow's business intent matches its permissions. Combine scanning with source review and a constrained runtime test.

Letting a package manager execute during inspection

Commands such as npx, pip install, and package lifecycle scripts can execute code. Resolve and review dependencies before installation, then install only inside the disposable environment.

Pinning a repository branch

A moving branch does not preserve what you reviewed. Pin the exact commit and nested dependency versions.

Giving the reviewer the same privileges as production

An untrusted instruction can influence an agent that reads it. Keep the first review raw and read-only, and keep the test environment free of valuable credentials and data.

Use a revision-first catalog as the starting point

A catalog can make provenance and review easier without replacing the audit. Aident Loadout Skills exposes a read-only skill detail view, the exact revision, referenced files, and a copyable Skill ID. Open one skill detail and record its revision plus every referenced capability before you decide whether its access matches your task.

For the architectural difference between instructions and integrations, read Agent Skills vs MCP vs CLI. For a practical security review method, see Claude Code security review without false positives. If a reviewed skill needs external services, use the Claude Code and Codex integration guide to keep provider credentials out of the repository.

Sources

• Agent Skills specification, accessed July 24, 2026

• Build skills, OpenAI, accessed July 24, 2026

• Agent Skills best practices, Anthropic, accessed July 24, 2026

• Agentic Skills Security Top 10 checklist, OWASP, accessed July 24, 2026

• Agent Skills in Microsoft Agent Framework, Microsoft, accessed July 24, 2026

• The New Attack Surface in Agent Skills, arXiv, February 6, 2026

• MalSkillBench: A Runtime-Verified Benchmark for Malicious Agent Skills, arXiv, June 8, 2026

This guide reflects the Agent Skills specification and security research available on July 24, 2026. Recheck the current specification, platform documentation, and exact skill revision before applying the workflow.