Security evidence for Agent Skills. A protective companion to Skillz Forge.
Skillz Shield is the OverKill Hill integration that checks committed skill packages with Cisco Skill Scanner and NVIDIA SkillSpector. It gives maintainers reviewable findings and makes missing analysis visible before they rely on a skill.
Its guiding phrase comes from The MurderBird: What the Water Kept: “Find what doesn’t hold.” Skillz Forge makes reusable capabilities discoverable; Shield examines their security risks.
Visit Skillz Shield for the public interface, scanner identities, security evidence, and installation guidance. The Vite, React, TypeScript, and Tailwind SPA is hosted on GitHub Pages. It reuses Forge's typography and visual language with an inverted, dark espresso palette.
The reusable GitHub Action runs independently of both websites. The repository
is OKHP3/skillz-shield, formerly skill-security-pipeline. Scanning takes place
in GitHub Actions; the browser displays public evidence and never receives
scanner credentials or executes submitted skills.
- Changed, committed skill packages and their supporting files. A change to a package reference, fixture, or script selects that package.
- Draft packages in declared skill families, even without a finished
SKILL.md, name, description, or license. Metadata completeness is not an admission gate. - Project support skills under
.agents/skills/and exported skills underskills/, identified by theirSKILL.mdmarkers.
Application-only changes produce an empty plan and skip vendor installation and scanning. Family administration, recognized migration locators, and unrelated archives are outside the inventory. Removed packages need no scan. The exact layout and exclusions are documented in Architecture.
Neither scanner executes submitted skill instructions, scripts, installers, or dependencies. Both use static security analysis without model credentials. NVIDIA's dependency analysis can contact OSV. This is not a skill quality, usefulness, or maturity evaluation; NVIDIA SkillEvaluator is not included.
Run on a disposable Ubuntu x86_64 GitHub-hosted runner with read-only permissions.
Pin Shield to a full commit SHA, keep scan state outside the source checkout, and
do not pass secrets to the scan. This example uses the released v1.0.2 code;
documentation on the main branch can describe changes awaiting the next release.
name: Skillz Shield
on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
jobs:
skills:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- name: Select skill packages
id: plan
uses: OKHP3/skillz-shield@b81aff7f323b47ae0747ff33571f3c9bc8ec60cb # v1.0.2
with:
mode: plan
state: ${{ runner.temp }}/skillz-shield-state
base: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event_name == 'push' && github.event.before || '' }}
full: ${{ github.event_name == 'workflow_dispatch' }}
- name: Resolve current stable scanner releases
if: steps.plan.outputs.scan == 'true'
uses: OKHP3/skillz-shield@b81aff7f323b47ae0747ff33571f3c9bc8ec60cb # v1.0.2
env:
GH_TOKEN: ${{ github.token }}
with:
mode: resolve
state: ${{ runner.temp }}/skillz-shield-state
- name: Install verified scanner environments
if: steps.plan.outputs.scan == 'true'
uses: OKHP3/skillz-shield@b81aff7f323b47ae0747ff33571f3c9bc8ec60cb # v1.0.2
with:
mode: install
state: ${{ runner.temp }}/skillz-shield-state
- name: Scan the selected skills
if: steps.plan.outputs.scan == 'true'
uses: OKHP3/skillz-shield@b81aff7f323b47ae0747ff33571f3c9bc8ec60cb # v1.0.2
with:
mode: scan
state: ${{ runner.temp }}/skillz-shield-state
- name: Keep sanitized evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: skillz-shield-evidence
path: |
${{ runner.temp }}/skillz-shield-state/plan.json
${{ runner.temp }}/skillz-shield-state/pins.json
${{ runner.temp }}/skillz-shield-state/report.json
if-no-files-found: ignore
retention-days: 14For automatic vendor-change rescans and weekly vulnerability-data refreshes, use the Skillz consumer workflow as the complete integration example. The action itself does not schedule jobs or change repository protection settings. If Actions are restricted, allow Shield and the pinned actions used by its action definition and your caller.
The operator CLI can scan a skill ZIP with its supporting files and produce downloadable JSON and standalone HTML results, including available file/line evidence and reviewed remediation guidance. See Whole-package scanning. The public Pages site does not yet accept uploads; public job hosting remains a separate deployment requirement.
| Decision | Meaning |
|---|---|
pass |
Both engines completed the requested static analysis with no high or critical findings. Lower-severity findings may still be present. |
review-required |
Both engines completed, and at least one high or critical finding needs review. |
incomplete |
At least one package could not be fully analyzed. Findings already obtained remain visible. |
review-required and incomplete produce a failing scan step. A failed resolution
or installation may stop before a report exists; that is not a passing scan.
Whether a failing job blocks merging is the consuming repository's decision.
The optional review action mode is a separate exact-content merge-policy
check for manually reviewed scanner limitations. It never edits report.json,
changes vendor severities, or reports a scan pass. On pull requests it reads
.github/skill-security-reviews.json from the PR's base commit, so the PR
cannot approve itself. Each record expires within 90 days and binds the exact
package SHA-256, vendor fingerprint, located high/critical findings, and
located NVIDIA reference_missing exceptions. Only fully inspected packages
with no other analysis gaps can receive this review outcome. Protect changes
to the review ledger and the consuming workflow through repository review
policy. See architecture for the record format and
fail-closed conditions.
Reports identify the source commit, package content digest, scanner versions and immutable artifacts, public rule IDs, severities, and coverage. They omit raw skill snippets and scanner diagnostics. No result certifies that a skill is safe, useful, mature, or ready for production.
See the technology inventory and update plan for declared versions, current stable release comparisons, and the weekly advisory freshness workflow alongside Dependabot's dependency-update pull requests.
The Shield control code stays pinned to a reviewed commit. On each actual scan, it resolves official stable scanner releases to immutable source commits, SHA-256-verified wheels, and vendor dependency locks. Compatible new releases are adopted automatically; a changed or incomplete report contract fails visibly. There is no vendor fork or copied rule collection to synchronize.
The Skillz consumer polls hourly. A new toolchain fingerprint prompts a full skill rescan, and a weekly refresh rechecks vulnerability data. A terminal report is cached as attempted, not passed, avoiding repeated full scans every hour. Manual runs always rescan. GitHub schedules are best effort: incorporation occurs at the next run, not immediately when a vendor publishes. Unreleased upstream branch edits are not installed.
| Path | Purpose |
|---|---|
| action.yml | Reusable action inputs, outputs, and runtime setup |
| entrypoint.py | Four-stage command interface: plan, resolve, install, scan |
| skill_security/ | Inventory, staging, vendor resolution, report adapters, and process supervision |
| tests/ | Contract tests and inert live-scanner smoke fixtures |
| site/ | Standalone Vite, React, TypeScript, and Tailwind public interface |
| scripts/ | Public evidence snapshot generation |
| .github/workflows/verify.yml | Adapter verification and real-engine smoke checks |
| Architecture | Scope rules, trust boundaries, action contract, and report flow |
| Roadmap | Web companion scope and follow-up opportunities |
| Contributing | Development and validation commands |
| Security policy | Private vulnerability reporting and operating boundaries |
| Changelog | Released changes and the project rename |
| AGENTS.md | Instructions for agents working in this repository |
Shield's integration code is MIT licensed, copyright OKHP3. Cisco Skill Scanner and NVIDIA SkillSpector are separate upstream projects, each under its own Apache-2.0 license: Cisco license and NVIDIA license. Their dependencies retain their respective licenses. This repository does not relicense upstream code or imply vendor endorsement.