Files
skillshare/website/docs/reference/commands/audit.md
T
Willie 355b42ee57 feat(cli): one frame and keymap for every TUI, inline prompts, file viewer (#370)
* 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
2026-10-04 04:14:47 +08:00

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):

  1. CLI flags (--profile, --threshold, --dedupe, --analyzer)
  2. Project config (.skillshare/config.yaml)
  3. Global config (~/.config/skillshare/config.yaml)
  4. 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 audit after 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 default CRITICAL, 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
  1. Install: Skills are automatically scanned — blocked if threshold exceeded
  2. Periodic scan: Run skillshare audit regularly to catch rules updated after install
  3. Pre-commit hook: Catch issues before they're committed with the pre-commit framework
  4. CI gate: Add audit to your CI pipeline for shared skill repositories
  5. Custom rules: Tailor detection to your organization's threat model
  6. Review reports: Use --format json for compliance, --format sarif for GitHub Code Scanning, or --format markdown for 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"

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.

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