audit

Scan installed skills for security threats and malicious patterns.

skillshare audit                        # Scan all installed skills
skillshare audit <name>                 # Scan a specific installed skill
skillshare audit <path>                 # Scan a file/directory path
skillshare audit --threshold high       # Block on HIGH+ findings
skillshare audit --json                 # JSON output
skillshare audit -p                     # Scan project skills

What It Detects

CRITICAL (blocks installation and counted as Failed)

Pattern	Description
`prompt-injection`	"Ignore previous instructions", "SYSTEM:", "You are now", etc.
`data-exfiltration`	`curl`/`wget` commands sending environment variables externally
`credential-access`	Reading `~/.ssh/`, `.env`, `~/.aws/credentials`

HIGH (strong warning, counted as Warning)

Pattern	Description
`hidden-unicode`	Zero-width characters that hide content from human review
`destructive-commands`	`rm -rf /`, `chmod 777`, `sudo`, `dd if=`, `mkfs`
`obfuscation`	Base64 decode pipes, long base64-encoded strings

MEDIUM (informational warning, counted as Warning)

Pattern	Description
`suspicious-fetch`	URLs used in command context (`curl`, `wget`, `fetch`)
`system-writes`	Commands writing to `/usr`, `/etc`, `/var`

LOW / INFO (non-blocking signal by default)

These are lower-severity indicators that contribute to risk scoring and reporting:

LOW: weaker suspicious patterns that still deserve review
INFO: contextual hints (for triage / visibility)

Example Output

┌─ skillshare audit ──────────────────────────────────────────┐
│  Scanning 12 skills for threats                             │
│  mode: global                                               │
│  path: /Users/alice/.config/skillshare/skills               │
└─────────────────────────────────────────────────────────────┘

[1/12] ✓ react-best-practices         0.1s
[2/12] ✓ typescript-patterns           0.1s
[3/12] ! ci-release-helper             0.2s
       └─ HIGH: Destructive command pattern (SKILL.md:42)
          "sudo apt-get install -y jq"
[4/12] ✗ suspicious-skill              0.2s
       ├─ CRITICAL: Prompt injection (SKILL.md:15)
       │  "Ignore all previous instructions and..."
       └─ HIGH: Destructive command (SKILL.md:42)
          "rm -rf / # clean up"
[5/12] ! frontend-utils                0.1s
       └─ MEDIUM: URL in command context (SKILL.md:3)

┌─ Summary ────────────────────────────┐
│  Scanned:  12 skills                 │
│  Passed:   9                         │
│  Warning:  2 (1 high, 1 medium)      │
│  Failed:   1 (1 critical)            │
└──────────────────────────────────────┘

Failed counts skills with findings at or above the active threshold (--threshold or config audit.block_threshold; default CRITICAL).

audit.block_threshold only controls the blocking threshold. It does not disable scanning.

Install-time Scanning

Skills are automatically scanned during installation. Findings at or above audit.block_threshold block installation (default: CRITICAL):

skillshare install /path/to/evil-skill
# Error: security audit failed: critical threats detected in skill

skillshare install /path/to/evil-skill --force
# Installs with warnings (use with caution)

skillshare install /path/to/skill --skip-audit
# Bypasses scanning (use with caution)

--force overrides block decisions. --skip-audit disables scanning for that install command.

There is no config flag to globally disable install-time audit. Use --skip-audit only for commands where you intentionally want to bypass scanning.

Difference summary:

Install flag	Audit runs?	Findings available?
`--force`	Yes	Yes (installation still proceeds)
`--skip-audit`	No	No (scan is bypassed)

If both are provided, --skip-audit effectively wins because audit is not executed.

Web UI

The audit feature is also available in the web dashboard at /audit:

skillshare ui
# Navigate to Audit page → Click "Run Audit"

Security Audit page in web dashboard

The Dashboard page includes a Security Audit section with a quick-scan summary.

Custom Rules Editor

The web dashboard includes a dedicated Audit Rules page at /audit/rules for creating and editing custom rules directly in the browser:

Create: If no audit-rules.yaml exists, click "Create Rules File" to scaffold one
Edit: YAML editor with syntax highlighting and validation
Save: Validates YAML format and regex patterns before saving

Access it from the Audit page via the "Custom Rules" button.

Exit Codes

Code	Meaning
`0`	No findings at or above active threshold
`1`	One or more findings at or above active threshold

Scanned Files

The audit scans text-based files in skill directories:

.md, .txt, .yaml, .yml, .json, .toml
.sh, .bash, .zsh, .fish
.py, .js, .ts, .rb, .go, .rs
Files without extensions (e.g., Makefile, Dockerfile)

Scanning is recursive within each skill directory, so SKILL.md, nested references/*.md, and scripts/*.sh are all inspected when they match supported text file types.

Binary files (images, .wasm, etc.) and hidden directories (.git) are skipped.

Custom Rules

You can add, override, or disable audit rules using YAML files. Rules are merged in order: built-in → global user → project user.

Use --init-rules to create a starter file with commented examples:

skillshare audit --init-rules         # Create global rules file
skillshare audit -p --init-rules      # Create project rules file

File Locations

Scope	Path
Global	`~/.config/skillshare/audit-rules.yaml`
Project	`.skillshare/audit-rules.yaml`

Format

rules:
  # Add a new rule
  - id: my-custom-rule
    severity: HIGH
    pattern: custom-check
    message: "Custom pattern detected"
    regex: 'DANGEROUS_PATTERN'

  # Add a rule with an exclude (suppress matches on certain lines)
  - id: url-check
    severity: MEDIUM
    pattern: url-usage
    message: "External URL detected"
    regex: 'https?://\S+'
    exclude: 'https?://(localhost|127\.0\.0\.1)'

  # Override an existing built-in rule (match by id)
  - id: destructive-commands-2
    severity: MEDIUM
    pattern: destructive-commands
    message: "Sudo usage (downgraded to MEDIUM)"
    regex: '(?i)\bsudo\s+'

  # Disable a built-in rule
  - id: system-writes-0
    enabled: false

Fields

Field	Required	Description
`id`	Yes	Stable identifier. Matching IDs override built-in rules.
`severity`	Yes*	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO`
`pattern`	Yes*	Rule category name (e.g., `prompt-injection`)
`message`	Yes*	Human-readable description shown in findings
`regex`	Yes*	Regular expression to match against each line
`exclude`	No	If a line matches both `regex` and `exclude`, the finding is suppressed
`enabled`	No	Set to `false` to disable a rule. Only `id` is required when disabling.

*Required unless enabled: false.

Merge Semantics

Each layer (global, then project) is applied on top of the previous:

Same id + enabled: false → disables the rule
Same id + other fields → replaces the entire rule
New id → appends as a custom rule

Practical Templates

Use this as a starting point for real-world policy tuning:

rules:
  # Team policy: detect obvious hardcoded API tokens
  - id: hardcoded-token-policy
    severity: HIGH
    pattern: hardcoded-token
    message: "Potential hardcoded token detected"
    regex: '(?i)\b(ghp_[A-Za-z0-9]{20,}|sk-[A-Za-z0-9]{20,})\b'

  # Override built-in suspicious-fetch with internal allowlist
  - id: suspicious-fetch-0
    severity: MEDIUM
    pattern: suspicious-fetch
    message: "External URL used in command context"
    regex: '(?i)(curl|wget|invoke-webrequest|iwr)\s+https?://'
    exclude: '(?i)https?://(localhost|127\.0\.0\.1|artifacts\.company\.internal|registry\.company\.internal)'

  # Governance exception: disable noisy path-write signal in your environment
  - id: system-writes-0
    enabled: false

Validate Changes

Typical workflow:

# 1) Create starter file (once)
skillshare audit --init-rules

# 2) Edit ~/.config/skillshare/audit-rules.yaml

# 3) Re-run audit to verify expected classification changes
skillshare audit

Summary interpretation:

Failed counts skills with findings at or above the active threshold.
Warning counts skills with findings below threshold but above clean (for example HIGH/MEDIUM/LOW/INFO when threshold is CRITICAL).

Built-in Rule IDs

Use id values to override or disable specific built-in rules:

Source of truth (full built-in definitions): internal/audit/rules.yaml

ID	Pattern	Severity
`prompt-injection-0`	prompt-injection	CRITICAL
`prompt-injection-1`	prompt-injection	CRITICAL
`data-exfiltration-0`	data-exfiltration	CRITICAL
`data-exfiltration-1`	data-exfiltration	CRITICAL
`credential-access-0`	credential-access	CRITICAL
`credential-access-1`	credential-access	CRITICAL
`credential-access-2`	credential-access	CRITICAL
`hidden-unicode-0`	hidden-unicode	HIGH
`destructive-commands-0`	destructive-commands	HIGH
`destructive-commands-1`	destructive-commands	HIGH
`destructive-commands-2`	destructive-commands	HIGH
`destructive-commands-3`	destructive-commands	HIGH
`destructive-commands-4`	destructive-commands	HIGH
`obfuscation-0`	obfuscation	HIGH
`obfuscation-1`	obfuscation	HIGH
`suspicious-fetch-0`	suspicious-fetch	MEDIUM
`system-writes-0`	system-writes	MEDIUM

Options

Flag	Description
`-p`, `--project`	Scan project-level skills
`-g`, `--global`	Scan global skills
`--init-rules`	Create a starter `audit-rules.yaml` (respects `-p`/`-g`)
`-h`, `--help`	Show help

install — Install skills (with automatic scanning)
doctor — Diagnose setup issues
list — List installed skills

What It Detects​

CRITICAL (blocks installation and counted as Failed)​

HIGH (strong warning, counted as Warning)​

MEDIUM (informational warning, counted as Warning)​

LOW / INFO (non-blocking signal by default)​

Example Output​

Install-time Scanning​

Web UI​

Custom Rules Editor​

Exit Codes​

Scanned Files​

Custom Rules​

File Locations​

Format​

Fields​

Merge Semantics​

Practical Templates​

Validate Changes​

Built-in Rule IDs​

Options​

Related​