The SkillSpector Install Gate
Scan the skill before your AI reads a single instruction.
SkillSpector is a free, open source security scanner from NVIDIA for AI agent skills used by Claude Code, Codex CLI, Gemini CLI, and similar tools. It scans a local folder, a single SKILL.md file, a zip file, or a Git repository before installation. It checks for prompt injection, secret collection, unexpected network calls, dangerous code, weak dependencies, excessive permissions, and other risks, then returns a score from zero to one hundred with a plain recommendation. This playbook gives you the quickest installation path, the exact commands, a company install policy you can paste into your own rules, and the limits that stop a clean score from becoming false confidence.
Why a text file now belongs in your software approval process
Most teams have a process for buying software. Someone checks the vendor, the permissions, the contract, and what company data the product can reach.
Agent skills often enter through a different door. A developer sees a useful skill in a post, downloads a folder, and drops it into Claude Code or another assistant. The folder may look like documentation. The agent reads it as instructions, and the bundle can also contain scripts, dependencies, tool definitions, and network calls.
That matters because the agent may already have access to your repository, terminal, browser, cloud accounts, internal documents, or environment variables. A malicious skill does not need to break into those systems itself. It only needs to persuade or instruct the agent that is already connected.
The research cited by SkillSpector collected 42,447 public skills and analyzed 31,132 of them. It reported that 26.1 percent of the analyzed skills contained at least one vulnerability, 5.2 percent showed high-severity patterns strongly suggesting malicious intent, and skills containing executable scripts were 2.12 times more likely to contain vulnerabilities.
Five percent sounds small until installing skills becomes normal across a company. At twenty installations, the odds stop feeling theoretical.
What SkillSpector does
SkillSpector reads analyzer-eligible files across the skill bundle without running the skill. It checks written instructions, scripts, dependency files, metadata, permissions, and declared behavior. Files outside its supported analysis scope and files over its per-file limit require separate review.
The current repository lists 71 detection patterns across 17 categories. The useful ones for a normal business include:
- Instructions that try to override the agent's safety rules.
- Code that reads passwords, tokens, SSH keys, or environment variables.
- Files that send data to an external server.
- Hidden instructions inside comments, metadata, or encoded text.
- Commands that fetch and execute remote scripts.
- Dependencies with known security problems.
- Permissions that are broader than the skill's stated job.
- A mismatch between what the skill says it does and what its code does.
- Persistence through startup files, scheduled jobs, or modified agent memory.
It runs two kinds of analysis. Static analysis checks the files with deterministic rules, Python code inspection, YARA signatures, and live dependency lookups. Optional semantic analysis sends eligible file contents to an LLM and asks whether the skill's stated purpose matches its behavior.
The output is a score from zero to one hundred, a severity, a recommendation, the affected file and line, and a plain-English explanation.
The five minute version
You need uv. Install SkillSpector directly from NVIDIA's repository:
uv tool install git+https://github.com/NVIDIA/skillspector.gitScan a public GitHub skill before installing it:
skillspector scan https://github.com/OWNER/REPOSITORY --no-llm --fail-on-incompleteScan a skill folder already on your machine:
skillspector scan ./path-to-skill --no-llm --fail-on-incompleteScan one instruction file:
skillspector scan ./SKILL.md --no-llm --fail-on-incompleteThe --no-llm flag keeps the first pass simple and avoids sending the skill's file contents to an external model. SkillSpector still sends declared dependency names and versions to OSV.dev for vulnerability checks when that service is reachable.
Read the recommendation before installing anything. Do not treat a completed scan as approval.
The install rule
SkillSpector's own score bands are easy to turn into a company rule:
| Score | Severity | Tool recommendation | Your action |
|---|---|---|---|
| 0 to 20 | LOW | SAFE | Continue to the manual checks below, then approve or reject. |
| 21 to 50 | MEDIUM | CAUTION | Pause. Review every finding and require a named person to accept it. |
| 51 to 80 | HIGH | DO NOT INSTALL | Block the installation until the source is fixed and rescanned. |
| 81 to 100 | CRITICAL | DO NOT INSTALL | Block it. Do not test it inside an agent connected to company systems. |
A low score only means the scanner did not find enough known warning signs to raise it. Before approving a skill, check these five things yourself:
The rest of this playbook is below.
Enter your email to read it. You also get one new playbook every week.
One email a week. Unsubscribe any time.
- Source. Is the repository owned by the company or person who claims to publish it?
- Scope. Does the skill need every tool and permission it requests?
- Scripts. Does it contain executable files? If yes, who read them?
- Network. Which domains can receive data, and does that match the stated job?
- Version. What exact commit or release did you approve?
If you cannot answer all five, the skill is not ready for a company-connected agent.
The company policy to paste into your own rules
Put this in your security handbook, AI policy, or agent setup instructions. Replace the bracketed fields.
AI SKILL INSTALLATION POLICY
No employee or agent may install an AI skill directly from a social post,
message, marketplace page, or search result.
Before installation:
1. Record the source repository and the exact commit or release.
2. Run SkillSpector against the complete skill bundle.
3. Save the report with the date, scanner version, and scan mode.
4. Review the skill's scripts, requested permissions, and external domains.
5. Name the person approving the installation.
Decision rule:
SAFE: Manual review still required before installation.
CAUTION: Installation requires written approval from [OWNER OR TEAM].
DO NOT INSTALL: Block until the source is fixed and a new scan passes.
A static-only scan must be labelled STATIC ONLY.
A failed or incomplete scan is not a pass.
A later update is a new artifact and must be scanned again.
Never test an unapproved skill inside an agent connected to production,
customer data, company repositories, shared drives, payment systems,
or live credentials.The last two lines are the part most companies miss. A scan belongs before installation, and every update resets the decision.
How to save a report someone else can review
Terminal output is useful while testing. A Markdown report is better for an approval record:
skillspector scan https://github.com/OWNER/REPOSITORY \
--no-llm \
--fail-on-incomplete \
--format markdown \
--output scan-report.mdJSON is the better format when you want an automated gate:
skillspector scan https://github.com/OWNER/REPOSITORY \
--no-llm \
--fail-on-incomplete \
--format json \
--output scan-report.jsonSARIF is available for code scanning systems and IDE tooling:
skillspector scan https://github.com/OWNER/REPOSITORY \
--no-llm \
--fail-on-incomplete \
--format sarif \
--output scan-report.sarifOne detail matters in automation. SkillSpector exits with code 0 for both SAFE and CAUTION. It exits with code 1 only when the score is above 50. If your company wants CAUTION to require approval, read the recommendation field in the JSON report instead of relying only on the exit code.
The full scan, and the privacy choice it creates
Static analysis catches suspicious strings, dangerous Python calls, known dependency problems, permission mismatches, hidden artifacts, and common exfiltration patterns. It is fast and does not send the skill's file contents to an LLM.
Semantic analysis checks intent. It can notice that a cooking assistant contains behavior with no connection to recipes, or that a harmless description sits above a script that searches for secrets and sends data away.
That extra judgment has a cost. With semantic analysis enabled, SkillSpector sends analyzer-eligible file contents to the model provider you configure. If the skill itself contains private company material, decide whether that provider is allowed to receive it before running the full scan.
For an OpenAI-backed scan:
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=your-key
skillspector scan ./path-to-skill --fail-on-incompleteFor an Anthropic-backed scan:
export SKILLSPECTOR_PROVIDER=anthropic
export ANTHROPIC_API_KEY=your-key
skillspector scan ./path-to-skill --fail-on-incompleteYou can also use authenticated Claude CLI or Codex CLI sessions without handing SkillSpector a separate API key. The official provider table lists the current setup for each option.
My rule would be simple. Run the static scan first. If it raises anything serious, stop there. Use semantic analysis only after the static pass and only with a provider your company already permits.
The part most coverage skips: the scanner is not a sandbox
NVIDIA says this directly: SkillSpector is defense in depth, not a sandbox.
It never executes the skill during analysis. That is good. It also means the scanner cannot observe what the skill will do only at runtime, what an encrypted or compiled file hides, or what text inside an image says. It can miss non-English attacks, and its LLM judgment can produce false positives or false negatives.
A SAFE result does not make the skill harmless. It means the scanner did not find enough evidence to classify it as unsafe under the checks it ran.
The fix is not another scanner. The fix is containment:
- Install the skill first in a test agent with no production credentials.
- Give the agent only the files and tools needed for that test.
- Keep sending, publishing, payments, account changes, and deletions behind approval.
- Record the exact version you approved.
- Scan again whenever the skill changes.
Scanning decides whether a skill deserves a test. Isolation decides how much damage a missed problem can do.
The three artifacts you need
One, the scan report. Save it as scan-report.md or scan-report.json. It should show the target, date, SkillSpector version, whether LLM analysis ran, the score, the recommendation, and every finding.
Two, the approval record. Create skill-decision.md. Record the source URL, exact commit, owner, requested permissions, external domains, report link, approver, decision, and next review date. A scan without a decision record disappears into a terminal window and teaches the company nothing.
Three, a written skill policy, 200 to 400 words, and almost nobody has one. Write which company systems an agent may reach, which data must never leave your environment, who can approve a CAUTION result, what actions always require human approval, and how quickly an update must be rescanned. The scanner can tell you what it found. This file tells your team what to do about it.
Using the NVIDIA verified catalog
When the skill you need already exists in the NVIDIA skills catalog, start there rather than from a repost or fork. NVIDIA's pipeline catalogs, scans, evaluates, signs, and documents skills before publication.
List the available NVIDIA skills without installing anything:
npx skills@latest add nvidia/skills --listWhen you have chosen a skill, install that specific skill with:
npx skills@latest add nvidia/skills --skill SKILL-NAME --yesVerified does not mean every future version is approved forever. Record the version you installed, keep the permissions narrow, and scan third-party forks separately.
If something goes wrong
| Problem | What to do |
|---|---|
skillspector command not found | Open a new terminal after the uv install, or run uv tool update-shell and restart the shell. |
| The scan asks for a model credential | Add --no-llm for the local static pass, or configure one of the supported providers before running semantic analysis. |
| The report says CAUTION but the command succeeded | This is expected when the analysis is complete. Exit code 0 covers SAFE and CAUTION. Exit code 1 covers a score above 50 and, when --fail-on-incomplete is present, an incomplete analysis. Read both risk_assessment.recommendation and analysis_completeness.is_complete in the JSON report. |
| A known dependency check appears incomplete | Confirm the machine can reach api.osv.dev. Without that connection, SkillSpector falls back to a smaller bundled list. |
| The skill is private | Clone it through your approved access method, then scan the local folder. Do not paste private credentials into a public URL. |
| The score looks wrong | Read the file and line behind each finding. Static checks favor catching suspicious patterns, so some findings need human context. Do not suppress one until someone records why it is acceptable. |
| A previously approved skill changed | Treat the update as a new artifact. Scan the new commit, compare the reports, and issue a new approval. |
Honest limits
SkillSpector can miss runtime-only behavior, encrypted or compiled code, text hidden in images, and some non-English attacks. Semantic analysis adds judgment, but that judgment can still be wrong.
The score is a triage device. A zero is not a warranty, and a CAUTION result is not automatically harmless because the process returned a successful exit code.
The scanner checks the skill bundle you point it at. It does not prove that the repository owner is honest, that the download was not replaced later, or that a safe skill cannot become dangerous after an update.
LLM analysis sends eligible file contents to the configured model provider. Static scans avoid that content transfer, but dependency names and versions may still go to OSV.dev for live vulnerability checks.
SkillSpector does not contain an installed skill. If you approve one, the agent still needs narrow permissions, a test environment, and human approval around sensitive actions.
The software is free under the Apache 2.0 license. Your cost is the time spent reviewing findings and any model usage you choose to add for semantic analysis.
What this changes
Agent skills used to feel like prompts. They now carry enough code, permissions, dependencies, and persistent instructions to deserve the same question you ask before installing software: who wrote this, what can it reach, and what happens when it runs?
SkillSpector turns that question into a repeatable check that takes minutes. The report gives you evidence. The install policy gives your team a decision. The isolated test limits the damage if both miss something.
The safe habit is simple: scan the exact version, save the report, name the approver, then install it with the smallest permissions that let it do its job.
