SkillGate is a local-first static trust gate for AI-agent skills, instruction files, helper scripts, and Model Context Protocol (MCP) metadata. It helps reviewers answer one practical question before install or merge:
What new agent capability would this code or configuration introduce?
SkillGate does not execute repository code, start MCP servers, call LLMs, or install remote packages. It scans files, reports capabilities and findings, and lets teams block unapproved behavior with policy-as-code.
Scan a public agent-skill repository before installing it:
python -m pip install "git+https://github.com/charliechenye/SkillGate.git@v0.1.0"
skillgate github scan https://github.com/addyosmani/agent-skills/tree/main/skills --fail-on highScan the current repository locally:
skillgate scan .Generate a starter policy when you are ready to block unapproved behavior:
skillgate policy init --profile strict --output skillgate.yaml
skillgate check . --policy skillgate.yaml| Use case | Start here | What you get |
|---|---|---|
| Scan a local skill or agent repo | skillgate scan . |
Nonblocking findings and capability inventory |
| Check a public GitHub skill repo before installing | skillgate github scan URL |
Sparse remote scan with immutable ref manifest |
| Block unapproved behavior in CI | skillgate check . --policy skillgate.yaml |
Policy violations, explanations, approvals, waivers |
| Detect capability drift after review | skillgate baseline create |
Stable lockfile and SG010 drift findings |
| Inspect MCP registry metadata without installing | skillgate mcp registry scan |
MCP tool, transport, package, and registry drift checks |
| Build a review inventory | skillgate inventory . |
Trust-boundary summary and filterable JSON |
| Upload findings to GitHub code scanning | --format sarif |
Stable SARIF alerts with capability tags |
Install the tagged release from GitHub:
python -m pip install "git+https://github.com/charliechenye/SkillGate.git@v0.1.0"
skillgate --helpYou can also install from the moving v0 compatibility tag:
python -m pip install "git+https://github.com/charliechenye/SkillGate.git@v0"For a fully immutable install, pin a commit SHA:
python -m pip install "git+https://github.com/charliechenye/SkillGate.git@FULL_COMMIT_SHA"Resolve the exact commit SHA with:
git ls-remote https://github.com/charliechenye/SkillGate.git refs/tags/v0.1.0
git ls-remote https://github.com/charliechenye/SkillGate.git refs/tags/v0v0.1.0 is the release tag. v0 is the moving compatibility tag for compatible
0.x Action releases. Teams that require maximum reproducibility should pin the
full commit SHA in install commands and GitHub Action references.
GitHub installs require Python 3.11 or newer and git on the customer machine. After a later PyPI publication, the short install path will be:
python -m pip install openevalgate-skillgateFor contributor or source-checkout development:
python -m pip install -e .
skillgate --helpUse scan when you want visibility without blocking anything:
skillgate scan .
skillgate scan . --severity high
skillgate scan . --format json
skillgate scan . --format sarif --output skillgate.sarif
skillgate scan . --fail-on highskillgate scan exits 0 even when findings exist unless you pass --fail-on medium|high|critical. It is a good first command for adoption, audits, and local review.
SkillGate scans agent instructions, skill files, scripts, package configs, MCP configs, and MCP registry metadata. It reports rules SG001 through SG013, covering shell execution, destructive actions, network egress, remote download execution, secret access, filesystem writes, prompt override language, obfuscation, MCP config discovery, MCP drift, MCP tool metadata risks, MCP transport risks, and MCP registry drift.
Useful follow-ups:
skillgate rules list
skillgate explain SG004Use github scan before copying or installing public skills or agent tooling:
skillgate github scan https://github.com/phuryn/pm-skills
skillgate github scan https://github.com/addyosmani/agent-skills/tree/main/skills
skillgate github scan https://github.com/phuryn/pm-skills --ref main --fail-on high
skillgate github scan https://github.com/phuryn/pm-skills --format json
skillgate github scan https://github.com/phuryn/pm-skills --manifest-output remote-manifest.jsonRemote scans are static and sparse. SkillGate resolves the requested branch or tag to an immutable commit SHA, fetches GitHub tree metadata at that SHA, downloads only supported agent files plus referenced local scripts, scans a temporary sparse mirror, and deletes it. It never executes remote repository content.
JSON output includes scan_report and remote_manifest. Use --manifest-output to save the manifest for text or SARIF scans. The manifest records the source URL, requested ref, resolved commit SHA, downloaded paths, SHA-256 hashes, byte counts, skipped files, and resource limits.
Full workflow: GitHub pre-install scans.
Use check when findings should block a merge or release:
skillgate policy init --profile strict --output skillgate.yaml
skillgate check . --policy skillgate.yaml
skillgate check . --policy skillgate.yaml --dry-run
skillgate check . --policy skillgate.yaml --format json
skillgate policy schema --output skillgate-policy.schema.jsonPolicy files support:
- durable capability approvals, such as
policy.network.allow,policy.shell.commands.allow,policy.filesystem.write,policy.secrets.env.allow,policy.capabilities.allow, and reviewed MCP baselines; - deny rules for capability groups and network categories;
- high-risk thresholds with
policy.risk_threshold.block; - rare expiring finding waivers under
policy.waivers.entries[].
Use capability approvals for expected behavior such as api.github.com, generated/**, or bash scripts/build.sh. Use finding waivers only when one specific risky finding remains risky but has been reviewed, for example a temporary waiver for one SG004 installer finding.
Docs and schema:
Use baselines when you want to approve the current capability set and catch future changes:
skillgate baseline create . --output skillgate.lock
skillgate diff . --baseline skillgate.lock
skillgate diff . --baseline skillgate.lock --fail-on-drift
skillgate diff . --baseline skillgate.lock --policy skillgate.yamlBaseline diffs are advisory by default and exit 0 so reviewers can inspect
drift before enforcing it. Add --fail-on-drift to block CI on any file,
capability, or MCP drift without a full policy file. Add --policy when drift
should be evaluated through policy rules such as policy.mcp.require_review_on_change.
Baseline diffs produce SG010 for MCP capability drift. Review expected MCP
changes, then update the baseline. Do not disable drift review just to make CI green.
Teams that want provenance for approved policy and baseline files can create a checksum manifest:
skillgate provenance create --policy skillgate.yaml --baseline skillgate.lock --output skillgate.provenance.json
skillgate provenance verify --manifest skillgate.provenance.jsonUse MCP registry commands when you want static review without installing or starting an MCP server:
skillgate mcp registry scan .
skillgate mcp registry scan mcp-registry.json --format json
skillgate mcp registry compare . --server io.example.server
skillgate mcp registry compare . --server io.example.server --fail-on-drift
skillgate mcp registry compare fixtures/registry-compare-drift/local \
--server io.example.registry-drift \
--registry-url fixtures/registry-compare-drift/registry.json \
--format sarif --output registry-drift.sarifRegistry scanning reads declared MCP registry metadata, publisher-provided tool metadata, remotes, packages, headers, and app-surface hints. Registry comparison is opt-in and reports SG013 when local declarations differ from registry or package metadata.
SG013 can be expected during a planned release, registry migration, package rename, endpoint cutover, or before local metadata has been published. Treat unexpected repository, package, remote endpoint, or secret-header drift as a review blocker until the intended source of truth is clear.
Example fixture: fixtures/registry-compare-drift.
Use inventory output when you want a review artifact rather than a pass/fail gate:
skillgate inventory .
skillgate inventory . --format json
skillgate inventory . --capability network_egress
skillgate inventory . --severity high
skillgate inventory . --source-file "scripts/*"Inventory output groups detected capabilities and findings by source file and summarizes trust boundaries for local execution, remote endpoints, secrets, generated files, MCP servers, prompt controls, and obfuscation.
Any scan that supports SARIF can be uploaded to GitHub code scanning:
skillgate scan . --format sarif --output skillgate.sarif
skillgate check . --policy skillgate.yaml --format sarif --output skillgate.sarif --dry-run
skillgate github scan https://github.com/OWNER/REPO --format sarif --output skillgate.sarif
skillgate mcp registry compare . --server io.example.server --format sarif --output registry-drift.sarifPlain scan SARIF reports static findings. Policy-aware check SARIF includes policy waiver and suppression metadata while --dry-run keeps SARIF generation from becoming a second blocking step. SARIF output includes deterministic alert fingerprints, stable run categories, capability tags, severity tags, and capability taxa. Local scans use skillgate/local-repository, remote GitHub scans use skillgate/remote-github, and MCP registry comparisons use skillgate/mcp-registry-compare.
The repository includes .github/workflows/skillgate.yml as a complete example workflow and a composite action for CI adoption:
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: "3.11"
- uses: charliechenye/SkillGate@v0
with:
path: .
sarif-output: skillgate.sarifAdd policy: skillgate.yaml when the repository has a policy file and should block unapproved behavior. Without policy, the Action runs a nonblocking scan. When both policy and sarif-output are supplied, the Action uploads policy-aware SARIF with waiver suppressions.
Copy-pasteable workflows: Minimal GitHub Action examples.
charliechenye/SkillGate@v0 is the stable Action channel for compatible 0.x releases. Teams that require immutable GitHub Action references should pin the Action to a full commit SHA, for example charliechenye/SkillGate@FULL_COMMIT_SHA, and update that SHA through their normal dependency review process.
SkillGate recursively discovers common agent-relevant files while skipping build, cache, dependency, virtual environment, and Git directories.
Supported files include:
**/SKILL.md**/AGENTS.md**/CLAUDE.md.github/copilot-instructions.md.claude/skills/**.agents/skills/**skills/**/SKILL.mdagents/**.claude/commands/**.gemini/commands/**hooks/****/mcp.json**/.mcp.json**/mcp-registry.json**/mcp-server.json- MCP registry-style
server.json package.jsonpyproject.toml- referenced local scripts ending in
.sh,.bash,.py,.js,.ts,.mjs,.cjs, or.ps1
To scan installed Codex skills from a source checkout without installing SkillGate:
python samples/scan_installed_skills.py
python samples/scan_installed_skills.py --root ~/.codex/skills --fail-on highSkillGate is static analysis and policy enforcement. It does not:
- execute scripts or package commands;
- install remote repositories or packages;
- start or introspect MCP servers at runtime;
- call LLM APIs;
- prove that a skill or server is safe.
Use it alongside sandboxing, least-privilege credentials, runtime monitoring, and human review.
skillgate fixtures summary fixtures/benchmark --format json
skillgate fixtures summary fixtures/benchmark --format text
python tools/update_snapshots.py --checkFixture summaries compare expected-findings.yaml files with actual scan output. Public-pattern fixtures include machine-readable attribution metadata.
Contributor docs:
SkillGate is a static AI-agent security scanner for skills, MCP configurations, instruction files, and helper scripts. It scans for risky capabilities before code is installed, merged, or run in CI.
Yes. SkillGate scans MCP config files, MCP registry metadata, MCP tool metadata, MCP transport metadata, and MCP capability drift. It can detect remote endpoints, secret-bearing headers, stdio package transports, localhost bridges, unauthenticated remote transports, and local-vs-registry metadata drift.
Yes. SkillGate discovers SKILL.md, .agents/skills/**, referenced scripts, package metadata, and related instruction files. It can also scan installed Codex skills from a source checkout with samples/scan_installed_skills.py.
Yes. SkillGate discovers common Claude-oriented layouts such as .claude/skills/**, .claude/commands/**, CLAUDE.md, and public agent-skill repository patterns.
Yes. skillgate github scan URL performs a sparse public GitHub scan without cloning the full repository or executing remote code. It resolves branches and tags to immutable commit SHAs and can emit a reproducible remote manifest.
No. SkillGate is static analysis. It does not execute scripts, run package commands, install dependencies, start MCP servers, introspect runtime tools, or call LLM APIs.
SkillGate detects shell execution, destructive commands, network egress, remote download execution, secret access, filesystem writes, prompt override language, Unicode obfuscation, MCP server configuration, MCP capability drift, MCP tool metadata risks, MCP transport risks, and MCP registry metadata drift.
A sandbox constrains runtime behavior. SkillGate reviews static files before runtime and helps teams decide whether a skill, MCP server, or agent-tooling change should be allowed at all. Use SkillGate alongside sandboxing, least-privilege credentials, runtime monitoring, and human review.
Use skillgate check . --policy skillgate.yaml to block unapproved behavior. For GitHub code scanning without policy, upload plain static SARIF:
skillgate scan . --format sarif --output skillgate.sarifWith policy and finding waivers, generate policy-aware SARIF so waiver suppressions are included:
skillgate check . --policy skillgate.yaml --format sarif --output skillgate.sarif --dry-runThe composite Action chooses the right SARIF mode automatically based on whether policy is supplied. See Policy schema reference, JSON Schema, and editor setup.
Capability approvals are durable policy allowlists for expected behavior, such as allowing api.github.com, allowing writes to generated/**, allowing bash scripts/build.sh, or approving an updated MCP baseline after review.
Finding waivers are rare, expiring exceptions for specific risky findings that remain risky but have been reviewed. They require owner, reason, creation date, expiry date, and optional ticket metadata under policy.waivers.entries[].
Yes. SkillGate emits SARIF 2.1.0 with stable alert fingerprints, run categories, capability tags, severity tags, and capability taxa for GitHub code scanning.
Yes. skillgate mcp registry compare compares local MCP registry metadata with a registry endpoint or fixture file and reports SG013 when repository URLs, package identifiers, remote URLs, transport types, versions, or secret/header requirements differ.
Use schemas/skillgate-policy.schema.json for policy editor integration, docs/policy-schema.md for policy details, docs/github-preinstall-scan.md for remote scans, and future_steps.md for roadmap planning.
See future_steps.md for planned adoption, PR review, MCP, and runtime-evidence work.