Tutorial: Govern at scale

The Govern stage is where Skillsmith stops being a personal tool and becomes infrastructure. It covers audit logs, SIEM export, security review, and compliance reporting — all backed by the owner/admin/member roles your team already has. Most flows here are Team or Enterprise tier.

This tutorial covers how you personally use Skillsmith at team scale, day to day — not the org-level registry lifecycle (publish, version, deprecate) described on the homepage and in the README. Those are two different things: this page is about auditing and monitoring skill usage across a team; the homepage is about publishing and versioning skills into the team registry.

These tutorials show Skillsmith in Claude Code. For installation in your preferred runtime (Cursor, Continue, Copilot, Windsurf), see Getting Started.

What you will do

• Query audit logs for a time range and event type
• Export audit events for compliance reporting
• Export events for a SIEM (CloudWatch, Splunk, Datadog)
• Run skill-level and pack-level security audits
• Read the session-start governance summary at the start of every Claude Code session
• Export a CycloneDX AI-BOM for compliance evidence

Tools that map to Govern

Step 1 — Audit a skill for security advisories

Before adding a skill to your team's approved set, run the security audit. It checks for known CVEs in declared dependencies, flagged authors, and structural patterns associated with malicious skills.

Try these prompts:

• "Audit community/jest-helper for security advisories"
• "Run a security audit on community/git-commit"
• "Check this skill for known vulnerabilities"

Or from the terminal:

skillsmith audit advisories community/jest-helper
skillsmith audit advisories --all   # Audit every installed skill

The audit returns a per-skill verdict (clean, advisory, blocked) with links to the underlying advisory feed. Treat blocked verdicts as hard stops; revisit advisory verdicts case-by-case.

Step 2 — Audit a pack of skills in bulk

For team rollouts you typically pack a curated set of skills together — a "frontend pack", "backend pack", "compliance pack" — and need to audit the whole pack at once.

Try this prompt:

• "Audit my team's approved skill pack for advisories"

The MCP tool skill_pack_audit takes a pack manifest, runs advisory checks on every skill in it, and returns a roll-up report. Use it before publishing internal pack updates so you do not roll out a skill with a new CVE attached.

Step 3 — Query the audit log

Every Skillsmith operation that mutates state (install, uninstall, update, pin, publish) writes an event to the audit log. The audit_query tool lets you read that log back filtered by actor, event type, and time range.

Try these prompts:

• "Show me Skillsmith audit events from the last 24 hours"
• "Query the audit log for installs by user @alice in March"
• "List uninstall events for community/jest-helper"

The MCP returns structured events (timestamp, actor, action, target, metadata). For ad-hoc analysis, ask Claude Code to summarize patterns: "Are there any unusual patterns in last week's audit events?"

Step 4 — Export audit events for compliance

Annual audit cycles, SOC 2 reviews, and customer security questionnaires all need exportable evidence. audit_export emits a sealed JSON or CSV bundle for a time range.

Try this prompt:

• "Export the Skillsmith audit log for Q1 2026 as JSON"

The export includes a SHA-256 manifest hash so the auditor can verify the bundle has not been tampered with. Store the bundle alongside your other compliance evidence; do not commit it to source control.

Step 5 — Export events for a SIEM

siem_export returns audit events for a time range in one of three formats: json, syslog, or cef. It targets SIEM tooling that ingests those formats (CloudWatch, Splunk, Datadog).

Try this prompt:

• "Export the last hour of Skillsmith audit events in CEF format"

The SIEM destination is configured via environment variables on the MCP server, not passed as a tool argument — siem_export itself just returns the formatted events for that time range; wiring the actual delivery to your collector is a deployment-time configuration step, not something the tool call does for you. A separate CloudWatch exporter can stream directly to AWS CloudWatch Logs. See the API reference for the wire format details.

Step 6 — Read the session-start governance summary

Team and Enterprise installs include a SessionStart hook in Claude Code that runs the namespace audit on every session and emits a summary on stderr. Free and Individual tiers see no output (intentional — the audit is a paid feature).

A typical Team summary looks like:

[skillsmith] audit: 0 collisions, 2 advisories pending review

The hook is debounced 24 hours (it does not fire on every session), and is bounded to a 5-second wall clock. Disable it with SKILLSMITH_SESSION_AUDIT_DISABLE=1 if it interferes with automation; logs land in ~/.skillsmith/logs/.

Step 7 — Apply rename and edit suggestions from your audit

The Maintain tutorial's namespace audit reports collisions and suggested fixes for your own ~/.claude/ inventory. There's no cross-team rollup yet — each developer runs the audit against their own machine.

Combine the audit output with apply_recommended_edit and apply_namespace_rename to act on those suggestions. Renames apply via the namespace-overrides ledger so subsequent audits respect them. This is per-suggestion remediation, not a configurable rules engine — each rename or edit is applied individually, the same way it is in Maintain.

Both apply tools return a non-mutating preview by default; pass confirmed: true to actually write the change. Neither tool is currently tier-restricted, and team-wide audit rollup across multiple developers doesn't exist yet.

Step 8 — Export a CycloneDX AI-BOM for compliance evidence

Regulatory and procurement obligations — EU AI Act technical-documentation requirements (Article 11 / Annex IV, for systems in the Annex III high-risk categories) and SBOM expectations flowing from US EO 14028 and its implementing OMB guidance — increasingly call for a machine-readable bill of materials, not just an audit log. compliance_report covers this: call it with format: "cyclonedx" to get a CycloneDX 1.5 AI/ML-BOM document of your installed skills, inferred dependencies, MCP server dependencies, and model requirements. The same tool also supports format: "soc2" and format: "json" for other compliance workflows.

Try this prompt:

• "Generate a CycloneDX AI-BOM for my installed skills"

If your machine hasn't run skill_rescan recently, the export legitimately comes back with dependencyDataSource: "pending-rescan" for some or all skills — the dependency graph hasn't been extracted yet, not a bug. Pass backfillDependencies: true on the same call to trigger that extraction inline during export instead of running skill_rescan separately first; this only takes effect on the native better-sqlite3 driver, not the WASM sql.js fallback some installs use. A mix of rescanned and not-yet-rescanned skills produces dependencyDataSource: "partial" — also expected, not an error.

Validate the output against the CycloneDX 1.5 JSON schema with @cyclonedx/cyclonedx-library's Validation.JsonStrictValidator (the same library Skillsmith validates with internally) or the official web validator at cyclonedx.org.

Common pitfalls

"License required" on every Govern call

Set SKILLSMITH_LICENSE_KEY in your MCP server's env config (not in your shell — MCP subprocesses do not inherit shell env). The license key resolves your team via the resolve_team_from_license RPC. If you have just upgraded and the error persists, restart the MCP server so it picks up the new env.

Audit log returns empty

Audit logs are scoped to your team. If you query without a license key or with a key that resolves to a different team, you see an empty result. Verify with "Who am I authenticated as?" before assuming the log is empty.

SIEM ingestion drops events

siem_export only formats and returns events — it does not deliver them. Most ingestion drops trace back to how your collector consumes that output: check the format (json, syslog, or cef) matches what your collector expects, and confirm whatever process forwards the export result to your SIEM is running and pointed at the right destination.

Where to next

The full personal-usage sequence ends at Uninstall — deliberately removing skills you no longer need from your own machine. For ongoing day-to-day hygiene, Govern's signals feed back into Maintain's actions.

Reference: MCP audit tools · CLI reference · API reference · Tier pricing.

Previous: Author — Next: Uninstall