About this skill

Why Skill Security Scanning is Necessary

Skill packages (.zip or directories) are essentially bundles of executable code and configurations. When installed or updated from third-party sources (skill hubs, GitHub, etc.), they can inadvertently introduce malicious scripts, backdoors, data leakage vulnerabilities, or content that violates platform policies. An uncontrolled skill can compromise workspace stability, exfiltrate sensitive information, or lead to privilege escalation. The core issue is the chain of trust. Users and platforms often cannot thoroughly audit an entire package at install time, necessitating an automated security gateway.

How SkillScan Works

SkillScan is a pre- and post-installation scanner designed to activate automatically at critical points in a skill's lifecycle.

Trigger Points: It activates whether invoked via commands like install, load, add, use, or in response to user actions such as uploading .zip/.skill files, pasting a SKILL.md, or mentioning an unknown skill name. This includes scanning .zip files before installation, directories after they land on disk, and remote installs immediately post-fetch.
Core Scanning Process:
1. Local Quick Scan: Executes scripts/scanner.py to analyze the skill directory or files locally.
2. Remote Result Lookup & Reporting: Local scan results (or file hashes) interact with a remote API (https://skillscan.tokauth.com). It first attempts a cache lookup, then uploads if necessary, and polls for the final result to ensure the latest security rule sets are applied.
3. Action Based on Verdict: The scanner communicates result severity via exit codes (0 to 3: UNKNOWN/SAFE, LOW/MEDIUM, HIGH/CRITICAL, scan failed), which dictates the next step: proceed, warn and ask for user confirmation, or block installation entirely.
Deep Integration with Agents: On first run, it appends a ## Skill Security rule to the SOUL.md file. This forces all agents to enforce scanning, maintaining a security baseline even when SkillScan isn't actively loaded. This rule is automatically removed upon uninstallation.
Silent Maintenance: The scanner checks for updates daily without requiring user interaction.

Boundaries and Caveats

Scan Scope: Focuses solely on the skill package (code, configuration files). It does not analyze runtime behavior or the host environment.
Result Interpretation: Installation proceeds only after an exit code of 0 (safe) or 1 (low/medium risk, with user confirmation). Code 2 (high/critical) results in a direct block. Accuracy depends on the underlying rule sets.
File Handling: The scanning process must not generate any report files inside the skill directory to avoid polluting the workspace. All temporary data and remote interactions are handled via the API.
Customization: The environment variable SKILL_SCANNER_UPDATE_URL can be set to point to a private update source, making it suitable for corporate intranets or customized scenarios.
Limitations: Scanning is static code and pattern analysis and cannot fully replace manual auditing. It may have false negatives against highly obfuscated or novel zero-day attacks.

Screenshots

Use Cases

Before installing a new skill from a skill hub or code repository, proactively trigger SkillScan to scan its `.zip` file or directory, using the exit code to decide whether to block installation to mitigate risks.
When an agent loads or evaluates a skill, if it detects it is unscanned or from an unknown source, automatically invoke SkillScan to perform a security check and return a risk level.
Periodically run `scanner.py scan-all` to batch-scan all installed skills, discovering newly identified vulnerabilities or non-compliant code due to updates in security rules.
As a skill developer, use SkillScan to pre-scan the skill package after local testing to ensure it passes basic security checks before publishing to a public repository.

Best For

Skill Platform Operations Staff: Need to ensure every skill installed by users is security-verified to prevent malicious code from contaminating the platform environment or stealing data.
AI Skill Developers: Want to embed automated security testing into the skill development cycle to meet release standards and fix potential issues proactively.
Enterprise AI Tool Administrators: Responsible for managing internally deployed skill libraries, requiring regular audits of skill packages to meet enterprise security compliance requirements.
Security Researchers or Test Engineers: Need to perform security assessments of third-party skills, using SkillScan's exit codes and reports to quickly determine risk levels.