Skill Audit

skill-audit

Security auditing CLI for AI agent skills.

When to Use This Skill

• When installing new skills from external sources
• When auditing existing skills for security issues
• When validating skills before distribution
• When investigating security alerts in skill dependencies
• When checking whether the local agent shell/config environment is safe before invoking skills
• When comparing current agent environment state against a trusted baseline

Quick Start

# Install globally
npm install -g @hungpg/skill-audit

# Audit skills
skill-audit -g              # Audit global skills (default mode is the canonical scan;
                            # exits 0 allowed / 1 rejected / 2 invalid or incomplete)
skill-audit -v              # Verbose output
skill-audit --json          # JSON for CI
skill-audit --threshold 5   # Advisory prioritization hint (does not affect exit code)

# Audit the agent execution environment
skill-audit doctor          # Read-only shell/config/PATH/hook scan
skill-audit trust env       # Save current environment baseline
skill-audit diff-env        # Detect drift from baseline

# Hook-friendly shell command assessment
skill-audit --check-command "npx skills add owner/repo"

Security Categories

Agent Environment Checks

skill-audit doctor checks risks outside a skill package, including:

• Agent hooks and config files
• Shell startup files
• PATH hijacking and workspace-local sensitive binaries
• MCP/tool command config risks
• Workspace instruction files such as AGENTS.md, CLAUDE.md, QWEN.md, and GEMINI.md
• Package lifecycle scripts that an agent might run through shell commands

Use skill-audit trust env and skill-audit diff-env to keep a compact trusted baseline across sessions. The baseline stores file hashes and redacted finding summaries, not full conversation history.

Session Context Contracts

Executable skills should declare the narrow session facts they read, the preconditions required before invocation, what they write back after execution, and when user confirmation is needed. skill-audit reports CTX-* findings when executable skills lack these boundaries.

Risk Scoring

• 0: Safe ✅
• 0.1-3.0: Risky ⚠️
• 3.1-7.0: Dangerous 🔴
• 7.1-10.0: Malicious ☠️

Postinstall Safety

This package includes a postinstall script for UX. It does NOT:

• Auto-install hooks
• Execute malicious code
• Make network requests
• Modify files without consent

See references/postinstall-safety.md for full documentation on postinstall patterns.