* chore(devcontainer): add a TUI screenshot kit Recreating the devcontainer wipes vhs and the browser it drives, so every TUI review started with a manual reinstall. The start script now installs the recording tools when they are missing and skips straight through when they are present. record-tui.sh screenshots each full-screen TUI in its own fresh ssenv, filled by tui-fixture.sh through real commands, so the TUI redesign can compare before and after on the same data. Refs #200 * feat(cli): ask small choices inline instead of full screen The restore source, new-skill wizard, install skill picker and the other checklist prompts each took over the whole screen for a handful of options, and the answer vanished once chosen. They now use the same inline prompt as init: the question appears in place, collapses into a "✓ label value" line, and stays in the scrollback. Lists longer than the visible rows can be narrowed with /, and esc inside the filter only leaves the filter. Every inline prompt shows one key line in the wording the full-screen TUIs will share. The new wizard drops its esc-goes-back steps: esc cancels, as in init. Refs #200 * feat(cli): give the list TUI the shared frame and keymap The full-screen TUIs each had their own header, footer and key letters, so the same action used different keys per screen and the help line listed everything at once. list is the first screen on a shared frame: one title line with scope, counts and tabs, the list and details side by side without dividers, and one key line with the common keys and the position. Everything else moves under ?, and confirmations ask on the key line so the list stays visible. Keys follow one lowercase letter per action (u update, d uninstall, t enable/disable, m manual only, ! audit). The All tab and the s status cycle are gone: tab switches skills and agents, and status: in the filter or --status covers enabled/disabled. Rows drop the group prefix that the heading above them already shows. Refs #200 * docs: drop key-by-key TUI instructions from command pages The command pages carried key tables, screen mock-ups and one bullet per key for every full-screen TUI, in five languages. The TUIs now show their keys on screen, so these pages repeated what the screen says and went stale with every key change (several already listed keys that no longer exist). Each TUI section is now one paragraph on what the screen shows and what it can do. What the screen does not explain stays: the filter tag syntax, what manual only does to SKILL.md, the analyze color thresholds, when audit opens its TUI, and that target changes are saved to config immediately. Refs #200 * feat(cli): move the trash TUI onto the shared frame The trash TUI replaced the whole screen with a confirmation and a spinner, so you lost sight of what you had selected, and r/d did nothing until something was ticked. It now uses the shared frame: checkbox rows with size and age, details beside them, and the confirmation, the names it covers, the running operation and its result on the bottom lines. With nothing selected, r and d act on the row under the cursor. Refs #200 * feat(cli): move the log TUI onto the shared frame Log rows were two-line "[date] COMMAND — status" blocks, stats lived behind s as a separate screen, and delete swapped the help bar for a prompt you could miss. Rows are now one line with time, command and a status mark; Entries and Stats are tabs on the title line next to the count and success rate; and the delete confirmation takes over the key line. With nothing selected, d deletes the entry under the cursor. Row delegates no longer force a 40-column minimum, which wrapped every row in lists narrower than that. Refs #200 * feat(cli): move the audit TUI onto the shared frame The audit TUI had its own tab bar, a divider column and a two-line summary footer, and esc quit even with a filter typed. It now uses the shared frame: scan counts and the Skills / Agents tabs on the title line, the worst severity at the right of each row, the scan-wide severity, threat and policy summary on the note line, and esc clears the filter before quitting. Rows under a group no longer repeat the group's name. Colored title facts keep their color instead of being dimmed. Refs #200 * feat(cli): move the audit rules TUI onto the shared frame The rules browser used keys no other screen shared: s for severity, space to toggle and R pressed twice to reset. It now follows the shared keymap: t turns a rule or pattern on or off, e asks for the new severity on the key line, and R asks yes/no before deleting audit-rules.yaml. The severity tabs sit on the title line, rows show the rule count or "off" at the right, and rule rows drop the pattern prefix the group row already shows. Space still toggles. When the title line is too narrow for every tab, it shows only the active one instead of clipping them. Refs #200 * feat(cli): move the analyze TUI onto the shared frame Analyze put the target switcher, a stats line and the help text in a three-line footer and sorted with s, which means sync everywhere else. It now uses the shared frame: skill count and always-loaded and on-demand tokens on the title line, one tab per target group, o to sort with the current order on the key line, and esc clears the filter before quitting. The details follow the list layout, and lint warnings use the ! mark the CLI uses. renderDetailSection and renderFactRow had no other callers and are removed. Refs #200 * feat(cli): move the diff TUI onto the shared frame The diff browser drew ruled separators, "── Next Steps ──" banners and an arrow before every suggested command, and esc quit with a filter typed. It now uses the shared frame: target, extra and difference counts on the title line, what differs at the right of each row, group rows like the list's, plain headings in the details, and esc clears the filter before quitting. Refs #200 * feat(cli): move the restore TUI onto the shared frame Restore replaced the whole screen for the confirmation, the running operation and the result, rendered two-line rows, and esc quit even with a filter typed. It now uses the shared frame: the target or the chosen target and its backup count on the title line, one-line rows with backup count and age or skill count and size at the right, and the confirmation, what it covers, the spinner and the result on the bottom lines. Esc clears the filter, then goes back, then quits. Refs #200 * feat(cli): move the MCP manager onto the shared frame and keymap The MCP manager used its own letters (a add, x remove, b backups, r refresh), hid the details behind Enter, and printed two help bars. It now uses the shared frame and the keys every other TUI uses: n add, i import, e edit, d remove, s sync, r restore, with the details of the selected server beside the list and ? for all keys. Refresh is gone because the manager reloads after every action. Command docs drop the key table, and the how-to page and built-in skill name the new keys. Refs #200 * feat(cli): move the search selector onto the shared frame The search selector rendered two-line checkbox rows, put the details under the list, used s for "search again" although s means sync everywhere else, and Enter with nothing selected silently cancelled. It now uses the shared frame with the keyword and counts on the title line, one-line rows with stars or risk at the right, and the details beside the list. Esc clears the filter, then goes back to the keyword prompt; Enter with nothing selected installs the row under the cursor, as r and d do in other TUIs. The command page drops its screen mock-up and key list, and no longer claims the search restarts after an install. Refs #200 * feat(cli): move the target TUI onto the shared frame and keymap The target TUI had five uppercase keys (M, N, I, E, R), a separate skills-or-agents picker before three of them, and full-screen pickers and remove confirmation. e now opens one menu of every setting the target has (skills mode, naming, include, exclude; agents mode, include, exclude, with agent filters marked as ignored in symlink mode), and the pickers and pattern editor open beside the list. d asks on the key line with the command it will run and what removal does. Patterns are added with n, as everywhere else. Also drops the filter style helper the MCP change left unused. Refs #200 * feat(cli): move the extras TUI onto the shared frame and keymap The extras TUI used six uppercase keys (N, X, S, C, M, F), each with its own full-screen menu, and a full-screen confirmation. It now uses the shared frame and keys: n new, d remove, s sync, c collect, and e for one menu with the mode and flatten setting of every target. The target menu and mode picker open beside the list, and confirmations ask on the key line with what the action does. The picker row helper moves to the shared frame, and the split and scroll-hint helpers no TUI uses any more are removed. Refs #200 * feat(cli): share one framed file viewer between list and extras The list and extras file viewers were two copies of the same layout with the old look: an indented title, a │ column between the tree and the file, and a hard-coded yellow cursor. Both now draw through one renderer in the shared frame: the skill or extra and the open file on the title line, the tree beside the file without a divider, and the scroll position at the end of the key line. Refs #200 * feat(cli): ask for a large repo's folder inline Installing from a repo with 50+ skills opened a full-screen folder browser with its own filter bar and key line, then dropped back to an inline skill checklist. The folder question is now an inline select like every other install prompt: the first choice installs everything below the current folder, esc goes up one level, and the chosen folder collapses into a "✓ folder" line before the skill list appears. The screenshot fixture gains a 60-skill repo so the picker can be recorded, and the filter-bar and page-info helpers that only the old picker used are removed. Refs #200 * feat(cli): ask for MCP and plugin values inline MCP and plugin values were typed into a separate textarea program that submitted on ctrl+d, a key no other prompt uses. They now go through a new ui.Text prompt drawn like the other inline questions: enter submits, alt+enter starts a new line, and the box grows with the value. The MCP name is a single line, so it uses ui.Input. Answers are not echoed afterwards because a value can hold a secret. Refs #200 * feat(cli): drop the full-screen MCP change preview Every MCP add, edit, remove, restore and sync already prints its plan inline and then asks whether to apply it. The full-screen preview in between showed the same changes again and needed one more enter, so it is removed along with the review step of the prompts interface. The confirm question loses its "Review complete" prefix, and a blank line now separates it from the plan. Refs #200 * feat(cli): ask extras init questions inline `extras init` without arguments ran its own full-screen wizard with a hand-drawn cursor and a different key line on every step. It now asks the same questions inline, like `init`: each answer collapses into a "✓" line, the target line shows where the file lands, and esc cancels with "Nothing was created". A new ui.InputValid keeps a question open and shows the error under it until the answer passes, which the name, file name and per-target file name questions need. Refs #200 * fix(cli): drop stale key hints from MCP prompts and help `mcp --help` still listed the manager keys from before its redesign (a add, x remove, b backups, r refresh), and several MCP and plugin questions repeated "Esc cancels" or claimed `a` selects all, while the key line under every prompt already shows the real keys (ctrl+a for all). The help now just says where the keys are, and the questions keep only what the key line cannot say. The MCP command page drops the same key list in all five locales. Refs #200 * feat(cli): open a skill's files at its audit findings The audit TUI listed each finding's file, line and one-line snippet, but judging whether a finding is real needs the lines around it, and that meant leaving the TUI to open the file by hand. Enter now opens the selected skill's files at its most severe finding, with the raw text numbered and the flagged line marked; n/N steps through the findings in the order the details number them, and the line above the keys says which finding is shown. The viewer state lives in a new fileBrowser so analyze and trash can open skills the same way. Long lines wrap under their text instead of being cut, since the evidence is often at the end of a line. Refs #200 * feat(cli): open a skill's files from analyze Analyze flags lint issues such as a description that is too short, but the screen only showed the description text, so fixing a skill meant finding its folder first. Enter now opens the selected skill's files, including local ones that live only in a target, as raw numbered text with the front matter, and the line above the keys repeats the first lint issue so it can be checked against what is written. Refs #200 * feat(cli): open a trashed item's files before restoring The trash TUI showed only the first fifteen lines of SKILL.md, which is not enough to tell two trashed versions apart or to see a skill's other files. Enter now opens the item's files in the same viewer as list and analyze, rendered as Markdown, and esc returns to the trash. Refs #200 * fix(cli): leave front matter out of the agent viewer in list Opening an agent in the list TUI rendered its whole file as Markdown, so the front matter came out as a horizontal rule and a "## name: ..." heading. Skills already drop it because the details panel shows the name and description; agents now read their body the same way. Refs #200 * test(cli): compare trash restore destinations home-relative The trash TUI shows restore destinations through shortenPath, so with HOME=/tmp, as in the offline Docker sandbox job, /tmp/skills prints as ~/skills and the tests that expected the absolute path failed. They now expect whatever shortenPath gives for the same path. Refs #200 * fix(cli): show control characters in viewed files as symbols The file viewers in list, extras, audit, analyze and trash wrote a file's bytes to the terminal as they were. Audit and analyze exist to inspect skills that may not be trusted, and a SKILL.md with an ESC or OSC sequence could rewrite the screen or the window title instead of being shown. Control characters are now replaced with same-width symbols such as ␛ before rendering, which keeps line numbers and the marked finding line in place; newlines and tabs are kept and CRLF is read as LF. Refs #200 * fix(cli): open audit findings in files the tree leaves out The file tree skips dotfiles and stops at three levels and 200 entries, but the audit scan reads root dotfiles and goes deeper. A finding in such a file, like a root .env, left the viewer on the previous file with the new finding's note above unrelated text. Opening a finding now adds its file to the top of the tree under its full relative path when it is missing, so the marked line is always the one reported. Refs #200 * fix(devcontainer): exit nonzero when a TUI screenshot fails to record record-tui.sh printed FAIL for a screen whose vhs run failed but still exited 0, so an unattended run looked like every screenshot was taken. It now remembers a failure, keeps cleaning up and recording the other screens, and exits 1 at the end. Refs #200 * fix(cli): keep other files' front matter and fit text to the pane Two problems in the shared file viewer: - It dropped YAML front matter from every Markdown file, so a trashed skill's README or template lost its metadata, which nothing else in the trash view shows. Only SKILL.md and a single-file agent drop it now, since their name and description appear in the details. - The open file was wrapped to at least 40 columns. In a narrow terminal that is wider than the right pane, so the layout wrapped each row a second time, breaking lines apart and moving the marked finding line. Text now wraps to the pane's real width. Refs #200 * fix(cli): keep frame lines within the terminal width joinEnds padded the title, confirm and filter lines but never cut them, so a long search query, path or command made the line wrap. Every TUI sizes its body for a fixed four lines of frame, so the wrap pushed the bottom of the body off the screen. Long text is now cut from the left side, keeping the status or tabs on the right. Lines are left alone until the terminal has reported its width. Refs #200 * fix(cli): show a nested skill's folder when no group heading names it List rows dropped the first path segment for every skill on the grounds that the group heading above shows it. With a single group, or a filter that leaves one, there is no heading, so frontend/react showed as just react and same-named skills from two folders looked alike. Rows now drop it only under a heading; a tracked skill's repo dir is still dropped as before. Refs #200 * fix(ui): let esc leave a prompt's filter after enter found nothing The inline prompt guessed the filter state from key presses and treated enter as leaving the filter. huh's Select stays in the filter when enter has no match, so the next esc, meant to leave the filter, cancelled the question instead: one folder level back in the large-repo picker, or the whole install at the top. The prompt now asks the field whether it is filtering. Refs #200 * fix(cli): show control characters in the trash preview as symbols The trash details panel prints the first lines of a trashed SKILL.md, and it wrote them to the terminal as they were. The file viewers already pass text through printableText so an ESC or OSC sequence in a skill is shown instead of acted on; the preview now does the same. Refs #200 * fix(cli): scroll an agent's text with the wheel anywhere in list An open agent has no file tree, but the wheel still treated the left quarter of the screen as the tree, so scrolling there did nothing. The whole screen now scrolls the agent's text. Refs #200 * fix(ui): read prompt answers after the prompt has run The prompt helpers returned "value, runPrompt(..., &value)". The Go spec leaves the order between reading value and the call unspecified, so a compiler may return the value from before the user answered. gc 1.25 runs the call first, so answers arrive today, but nothing guarantees it. Each helper now runs the prompt into err and then returns the value. Refs #200 * fix(cli): name hidden Unicode and skip oversized files in the viewer Two gaps in the file viewer used to inspect untrusted skills: - Zero-width and bidirectional characters passed through unchanged, although the audit reports them as HIGH (Trojan Source). Opening such a finding reordered or hid the text instead of showing the cause. They now appear as <U+202E> and the like. - Moving onto a file read all of it, then copied it again while numbering and wrapping, with no size limit. The audit skips files over 1 MB; the viewer now does too and says the file is too large. Refs #200 * fix(cli): show control characters in viewed file names as symbols File contents in the viewer already pass through printableText, but the tree and the title printed file and skill names as they were. A file named with an ESC sequence, a newline or a bidirectional character in a skill under review could still reach the terminal, or break the frame across lines. Names now go through printableName, which also shows a newline or tab as a symbol so the name stays on one line. Refs #200
17 KiB
sidebar_position
| sidebar_position |
|---|
| 3 |
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 a b c # Scan multiple skills
skillshare audit --group frontend # Scan all skills in a group
skillshare audit <path> # Scan a file/directory path
skillshare audit --threshold high # Block on HIGH+ findings
skillshare audit -T h # Same as --threshold high
skillshare audit --format json # JSON output
skillshare audit --format sarif # SARIF 2.1.0 output (GitHub Code Scanning)
skillshare audit --format markdown # Markdown report (for GitHub Issues/PRs)
skillshare audit --json # Same as --format json (deprecated)
skillshare audit -p # Scan project skills
skillshare audit --quiet # Only show skills with findings
skillshare audit --yes # Skip large-scan confirmation
skillshare audit --no-tui # Plain text output (no interactive TUI)
skillshare audit --profile strict # Use strict profile (block on HIGH+)
skillshare audit --dedupe global # Full composite-key deduplication
skillshare audit --analyzer static # Run only the static analyzer
skillshare audit --analyzer static --analyzer dataflow # Multiple analyzers
When to Use
- Review security findings after installing a new skill
- Scan all skills for prompt injection, data exfiltration, or credential access patterns
- Customize audit rules for your organization's security policy
- Generate audit reports for compliance (
--format json), static analysis tools (--format sarif), or documentation (--format markdown) - Integrate into CI/CD pipelines to gate skill deployments
- Upload SARIF results to GitHub Code Scanning for PR-level annotations
What It Detects
The audit engine scans every text-based file in a skill directory against 100+ built-in rules (regex patterns, table-driven credential detection, structural checks, content integrity verification, and supply-chain trust analysis), organized into 5 severity levels: CRITICAL, HIGH, MEDIUM, LOW, and INFO.
For the full detection catalog, threat categories deep dive, risk scoring algorithm, command safety tiering, and cross-skill interaction analysis, see Audit Engine.
Example Output
skillshare audit
Audit ~/.config/skillshare/skills
global · blocks at CRITICAL · policy DEFAULT / dedupe:GLOBAL / analyzers:ALL
! ci-release-helper HIGH · risk 25/100
✗ suspicious-skill CRITICAL · risk 35/100
Summary
Scanned 12 skills
✓ Passed 9
! Warning 2
✗ Failed 1
Severity 1 critical, 2 high, 1 medium
Threats credential:1 exfiltration:1 injection:1 privilege:1
Risk HIGH 35/100 · 100% auditable
✗ Blocked 1 of 12 skills: findings at CRITICAL or above · 2.1s
The risk score is informational; only the severity blocks
Next
skillshare audit suspicious-skill see its findings
Failed counts skills with findings at or above the active threshold (--threshold or config audit.block_threshold; default CRITICAL).
Threats shows a category breakdown of all findings using short names: inj (injection), exfil (exfiltration), cred (credential), obfusc (obfuscation), priv (privilege), integ (integrity), struct (structure), risk (risk). This line is omitted when there are no findings. In terminal output, each category is color-coded by threat type.
audit.block_threshold only controls the blocking threshold. It does not disable scanning.
Interactive TUI Mode
When scanning several skills in an interactive terminal, audit opens a full-screen view instead of printing results line by line: skills on the left with findings first, and the risk summary and findings of the selected skill on the right. Opening a skill shows its files at each finding, with the flagged line marked and its line number. The keys are listed at the bottom of the screen.
It opens only when the terminal is interactive, the output is not JSON, and there is more than one result. Use --no-tui to force plain text.
Large Scan Confirmation
When scanning more than 1,000 skills in an interactive terminal, the command prompts for confirmation before proceeding. Use --yes to skip this prompt in TTY environments (e.g., local automation scripts). In CI/CD pipelines (non-TTY), the prompt is automatically skipped.
Policy & Profiles
The audit command supports policy-driven configuration through profiles, deduplication modes, and analyzer selection. These can be set via CLI flags, project config, or global config.
Profiles
Profiles are presets that set sensible defaults for threshold and deduplication:
| Profile | Threshold | Dedupe | Use case |
|---|---|---|---|
default |
CRITICAL |
global |
Standard behavior — block only critical threats |
strict |
HIGH |
global |
Security-conscious teams — block high+ threats |
permissive |
CRITICAL |
legacy |
Advisory-only — minimal blocking, no global dedup |
skillshare audit --profile strict # Block on HIGH+, global dedup
skillshare audit --profile permissive # Advisory mode
Explicit flags always override profile defaults:
skillshare audit --profile strict --threshold medium # strict profile but block on MEDIUM+
Deduplication
When the same finding is detected by multiple analyzers (e.g., both static and dataflow), deduplication removes redundant entries:
| Mode | Behavior |
|---|---|
global |
Full composite-key dedup across all findings (default) |
legacy |
Per-analyzer dedup only (pre-v0.16.9 behavior) |
Analyzer Selection
By default all analyzers run. Use --analyzer to run only specific ones:
skillshare audit --analyzer static # Static pattern matching only
skillshare audit --analyzer static --analyzer dataflow # Multiple analyzers
| Analyzer | Scope | Description |
|---|---|---|
static |
Per-file | Regex-based pattern matching against audit rules |
dataflow |
Per-file | Taint tracking for shell scripts and markdown code blocks |
tier |
Per-skill | Capability tier combination risk analysis |
integrity |
Per-skill | Content hash verification (file_hashes in SKILL.md) |
metadata |
Per-skill | Supply-chain trust verification (publisher mismatch, authority claims) |
structure |
Per-skill | Dangling markdown link detection |
cross-skill |
Bundle | Cross-skill exfiltration and privilege escalation analysis |
You can also set this in config:
audit:
enabled_analyzers: [static, dataflow]
Precedence
Settings resolve in this order (first non-empty wins):
- CLI flags (
--profile,--threshold,--dedupe,--analyzer) - Project config (
.skillshare/config.yaml) - Global config (
~/.config/skillshare/config.yaml) - Profile defaults
Automatic Scanning
Install-time
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 --audit-threshold high
# Per-command block threshold override
skillshare install /path/to/skill -T h
# Same as --audit-threshold high
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.
Update-time
skillshare update runs a security audit after pulling tracked repos. Findings at or above the active threshold (audit.block_threshold by default, or --audit-threshold / --threshold / -T override) trigger rollback. See update --skip-audit for details.
Findings you accept with --force are remembered for that skill, so later updates do not block on the same rule matching the same text. A new finding, or the same rule matching different text, blocks again. See Accepted Findings.
When updating tracked repos via install (skillshare install <repo> --track --update), the gate uses the same threshold policy (audit.block_threshold or --audit-threshold / --threshold / -T).
CI/CD Integration
The audit command is designed for pipeline automation. In non-TTY environments (CI runners, piped output), the interactive TUI and confirmation prompt are automatically disabled — no --yes or --no-tui needed.
For complete CI/CD workflows (GitHub Actions, GitLab CI, SARIF upload, output formats), see the CI/CD Skill Validation recipe.
Pre-commit Hook
Run skillshare audit automatically on every commit using the pre-commit framework. The hook scans files matching .skillshare/ or skills/ directories and blocks the commit if findings exceed your configured threshold.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/runkids/skillshare
rev: v0.16.11 # use latest release tag
hooks:
- id: skillshare-audit
See the Pre-commit Hook recipe for full setup instructions.
Best Practices
For Individual Developers
- Audit before trusting — always run
skillshare auditafter installing skills from untrusted sources - Review findings, not just pass/fail — a "passed" skill may still have LOW/MEDIUM findings worth investigating
- Read skill files — automated scanning catches known patterns, but novel attacks require human review
For Teams and Organizations
- Set
audit.block_threshold: HIGH— stricter than the defaultCRITICAL, catches obfuscation and destructive commands - Create organization-wide custom rules — add patterns for internal secret formats (e.g.,
corp-api-key-*) - Use project-mode rules for overrides — downgrade expected patterns per-project rather than globally
Recommended Audit Workflow
- Install: Skills are automatically scanned — blocked if threshold exceeded
- Periodic scan: Run
skillshare auditregularly to catch rules updated after install - Pre-commit hook: Catch issues before they're committed with the pre-commit framework
- CI gate: Add audit to your CI pipeline for shared skill repositories
- Custom rules: Tailor detection to your organization's threat model
- Review reports: Use
--format jsonfor compliance,--format sariffor GitHub Code Scanning, or--format markdownfor GitHub Issues/PRs
Threshold Configuration
Set the blocking threshold in your config file:
# ~/.config/skillshare/config.yaml
audit:
block_threshold: HIGH # Block on HIGH or above (stricter than default CRITICAL)
Or per-command:
skillshare audit --threshold medium # Block on MEDIUM or above
Full Audit Configuration
All audit settings can be persisted in config.yaml:
# ~/.config/skillshare/config.yaml (or .skillshare/config.yaml for project)
audit:
block_threshold: HIGH # Blocking severity gate
profile: strict # Profile preset (default/strict/permissive)
dedupe_mode: global # Dedup mode (global/legacy)
enabled_analyzers: [static, dataflow, tier] # Limit to specific analyzers
CLI flags override config values. See Precedence for full resolution order.
The skillshare status command displays the resolved audit policy, showing the effective profile, threshold, dedupe mode, and analyzer list after applying all precedence layers.
Web UI
The audit feature is also available in the web dashboard at /audit:
skillshare ui
# Navigate to Audit page → Click "Run Audit"
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.yamlexists, 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.
Options
| Flag | Description |
|---|---|
-G, --group <name> |
Scan all skills in a group (repeatable) |
-p, --project |
Scan project-level skills |
-g, --global |
Scan global skills |
--threshold <t>, -T <t> |
Block threshold: critical|high|medium|low|info (shorthand: c|h|m|l|i, plus crit, med) |
--profile <p> |
Audit profile preset: default, strict, permissive |
--dedupe <mode> |
Dedup mode: legacy, global (default) |
--analyzer <id> |
Only run specified analyzer (repeatable). IDs: static, dataflow, tier, integrity, metadata, structure, cross-skill |
--format <f> |
Output format: text (default), json, sarif, markdown |
--json |
Output JSON (deprecated: use --format json) |
--yes, -y |
Skip large-scan confirmation prompt (auto-confirms) |
--quiet, -q |
Only show skills with findings + summary (suppress clean ✓ lines) |
--no-tui |
Disable interactive TUI, print plain text output |
--init-rules |
Create a starter audit-rules.yaml (respects -p/-g) |
-h, --help |
Show help |
Subcommands
| Subcommand | Description |
|---|---|
rules |
Browse, enable, and disable audit rules (see audit rules) |
Agent Support
skillshare audit agents scopes the security scan to agents only, scanning .md files in the agents source directory:
skillshare audit agents # Scan all agents
skillshare audit agents --threshold high # Block on HIGH+ for agents
skillshare audit agents --format sarif # SARIF output for agents
skillshare audit agents -p # Scan project agents
Agents are subject to the same audit rules, severity levels, and threshold gating as skills. Without the agents argument, audit scans skills only (default behavior). See Agents for background.
See Also
- Audit Engine — How the engine works (threat model, risk scoring, command tiering)
audit rules— Rule management and customization- install — Install skills (with automatic scanning)
- check — Verify skill integrity and sync status
- doctor — Diagnose setup issues
- list — List installed skills
- Securing Your Skills — Security guide for teams and organizations
- CI/CD Skill Validation — Pipeline automation recipe
- Pre-commit Hook — Automatic audit on every commit
- Agents — Agent concepts
