SkillTrustOps

SkillTrustOps finds unsafe instructions, secrets, personal data, dangerous code, and risky package structure before an agent loads a skill. Its core primitive is a policy-bound scan report: deterministic findings with stable rule IDs, evidence, and exit codes for local review or CI.

Try it

python -m pip install skilltrustops
skilltrustops policy init --profile recommended-v2
skilltrustops scan .
# Optional depth, still one workflow:
skilltrustops scan . --redteam --benchmark
skilltrustops scan . --debt-report engineering-debt.md
# 0 = passed, 1 = findings, 2 = scanner or configuration error

What it does

Need	What SkillTrustOps provides
Review one or many skills	Recursive discovery, one policy, stable ordering, per-skill timing
Inspect the full package	SKILL.md, scripts, references, assets, manifests, dependencies, archives, and symlinks
Find static risk	Structure, secrets, PII, dangerous code, injection, obfuscation, persistence, exfiltration, permissions, lifecycle, and cross-file rules
Use it in CI	Exit-code contract, JSON, SARIF 2.1.0, expiring suppressions, fingerprinted baselines
Test behavior	Synthetic data, simulated tools, deterministic assertions, immutable evidence
Stay offline	Static scanning and reference red-team testing without an API key
Verify claims	Locked corpus, Docker resource limits, raw runs, checksums, calibration metrics

See invariants and failure modes for what the scanner guarantees, and anti-patterns for unsafe ways to integrate it. Production integrations can use the documented structured logging and OpenTelemetry spans.

Requirements and installation

SkillTrustOps requires Python 3.11 or newer.

python -m pip install skilltrustops
skilltrustops --help

Until the first PyPI release, install a locally built wheel or the Git repository instead. The package exposes both the skilltrustops CLI and skilltrustops.scan Python API.

Capability	Network or OpenAI key required?
Recursive lint, security, and privacy scan	No
Docker benchmark reproduction	No after corpus and container image inputs are available locally
Reference-provider red-team harness validation	No
Deterministic red-team manifest generation	No
Red-team assessment of a live model	Yes; use OpenAI or a generic HTTPS provider

Offline red-team runs validate the harness, fixtures, attack assertions, evidence format, and deterministic reference behavior. They do not establish how an unqueried production model will behave.

Catch unsafe skill instructions before an agent follows them

Run the quality gate with one command:

uv run skilltrustops scan .

You get a local, deterministic pass or fail for skill structure, exposed credentials, dangerous instructions, and personal data. Start with Getting started for installation alternatives and behavioral testing.

Scan one skill or a folder

Apply one policy to every SKILL.md below a folder and emit deterministic evidence:

uv run skilltrustops scan path/to/skills \
  --policy skilltrustops.yaml \
  --format json > skilltrustops-report.json

For code scanning platforms, change the format to SARIF. To create a local Git gate, install the supplied pre-commit and pre-push hook. CI must run the same scan because local hooks can be bypassed.

skilltrustops scan path/to/skills --format sarif > skilltrustops.sarif

See Git hooks and exit codes and rule compatibility.

The same stable report is available from Python:

from skilltrustops import scan

report = scan("path/to/skills", policy_path="skilltrustops.yaml")
for skill in report.skills:
    print(skill.relative_path, skill.status)

Folder discovery is recursive, deterministic, and limited to regular, non-symlink files named SKILL.md. A failed skill produces findings while a scanner failure is reported separately as an error; errors are never counted as passes.

[!IMPORTANT] Static checks never execute the submitted skill or upload its content. Red-team runs call the model provider you select. All tools used by the red-team harness are in-memory simulations and perform no real side effects.

Three gates to trust

SkillTrustOps evaluates a skill in three stages: structure, security and privacy, then model behavior under attack.

Control scan depth

uv run skilltrustops scan . --security --privacy
uv run skilltrustops scan . --redteam
uv run skilltrustops scan . --benchmark
uv run skilltrustops scan . --metrics

Security and privacy are enabled by default. --no-security and --no-privacy exist for focused troubleshooting, not for certification. --benchmark verifies that a replay produces identical evidence. --metrics opts into nondeterministic wall-clock timings and cannot be combined with the replay check.

What the security scan checks

The security stage reads the complete adjacent skill package under strict file, byte, archive, and symlink limits. It checks text and known manifests for credentials, dangerous execution, prompt injection, obfuscation, persistence, exfiltration, excessive permissions, lifecycle hooks, unsafe archives, unpinned dependencies, and risky cross-file delegation. It never follows links or executes package content. Sensitive matches are redacted from output.

See Security scan for the complete rule list, execution flow, configuration, and scope limits.

Evidence, explanations, and engineering debt

skilltrustops certify .
skilltrustops explain STO-SEC-103 --report scan.json
skilltrustops scan . --debt-report engineering-debt.md

certify is an evidence matrix, not a blanket badge: unsupported controls are shown as NOT ASSESSED. explain connects a stable rule ID to observed evidence, risk, remediation, and primary references. The debt report groups and prioritizes the same findings without inventing a score.

Agent-to-Skill trust boundary

SkillTrustOps is a pre-trust review gate. It evaluates an untrusted skill before a reviewer allows an agent runtime to load it; it is not an inline production proxy.

Static review stays local

Red-team testing uses simulated tools

Red-team a skill

After creating and reviewing an adjacent behavioral manifest, use the same scan workflow:

uv run skilltrustops scan path/to/SKILL.md --redteam

This primary workflow uses the offline deterministic reference target. Advanced live-provider and sandbox configuration remains in red-team testing.

Measured on 605 public skills

The final lean-package benchmark used Python 3.11, seven Docker CPU/memory profiles, five complete runs per profile, and no model or API key. Timed containers had networking disabled.

Docker limit	Median for 605 skills	Throughput	Peak memory
0.25 CPU / 1 GiB	57.694 s	10.486 skills/s	126.3 MB
1 CPU / 512 MiB	26.031 s	23.242 skills/s	127.3 MB
1 CPU / 1 GiB	25.484 s	23.740 skills/s	123.7 MB
2 CPU / 1 GiB	25.398 s	23.821 skills/s	124.4 MB

All 605 skills completed with zero scanner errors. 137 passed the selected policy and 468 produced findings for review. Those counts are not labels of safe or malicious content. The public corpus has no adjudicated ground truth.

Open the interactive benchmark, read the plain-English summary, or verify the compressed raw results and checksums in results/library-2026-08-05. The 500-case calibration report is a constructed regression result, not an independent real-world accuracy claim.

Documentation

Guide	Use it when you need to…
Documentation home	Find the right guide and understand the trust model.
Getting started	Install SkillTrustOps and complete a first assessment.
Policy guide	Create, validate, discover, and maintain skilltrustops.yaml.
Policy reference	Look up every supported policy field and constraint.
Security scan	Understand secret and dangerous-instruction checks, execution flow, and limits.
Red-team testing	Decide when to test, activate it, review manifests, and interpret evidence.
Security best practices	Operate SkillTrustOps safely in development and CI.
Troubleshooting	Resolve common policy, provider, sandbox, and exit-code failures.

What the decisions mean

Decision	Meaning
passed_scope	Every applicable case passed for the exact approved package, model, harness, sandbox boundary, and attack definitions recorded in evidence.
blocked	At least one deterministic assertion confirmed a security failure.
inconclusive	Required evidence was missing or uncertain, a draft was unapproved, or the configured isolation boundary was non-certifying.

passed_scope is scoped evidence, not a universal safety guarantee. Never convert inconclusive into a pass.

Development

uv run --extra dev pytest
uv run --extra dev ruff check .
uv run --extra dev mypy src
uv build

License

Apache-2.0. See LICENSE.