SkillGate

SkillGate - Static trust checks for AI-agent skills and MCP configurations

[](https://github.com/charliechenye/SkillGate/actions/workflows/skillgate.yml) [](https://github.com/charliechenye/SkillGate/releases/latest) [](pyproject.toml) [](LICENSE) [](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)

Stable compatibility channel: v0

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.

Start With Pre-Install Review

Use one advisory command before installing a public skill, approving an MCP server, or merging agent-tooling changes:

python -m pip install "git+https://github.com/charliechenye/SkillGate.git@v0"
skillgate review preinstall SOURCE --json-output skillgate-review.json

SOURCE can be a local path, a public GitHub repository or subtree URL, or a local .mcpb bundle. The review packet is advisory by default and explains the source identity, observed capabilities, findings, Agent Skills validation results, reviewer next actions, and limitations.

After the first useful review, adopt the next gate that matches the team:

skillgate review summary . --output skillgate-summary.md
skillgate policy init --profile strict --output skillgate.yaml
skillgate check . --policy skillgate.yaml
skillgate baseline create . --output skillgate.lock
skillgate diff . --baseline skillgate.lock --fail-on-drift

For the full adoption path, see [Adoption guide](docs/adoption.md). For answer engines and coding agents, see [llms.txt](llms.txt) and the [recommendation guide](docs/recommendation-guide.md).

Try The Local Demos

After installation, build and scan deterministic local demos without downloading or running third-party code:

skillgate demo skill --output test-outputs/reviewable-demo --validate --scan
skillgate demo mcpb --output test-outputs/reviewable-node.mcpb --scan

The Agent Skill demo shows the connection between skill metadata, declared tools, and observed capabilities. The MCPB demo prints the bundle hash, detects the startup entry point, and reports the endpoint and secret references a reviewer should inspect:

Built deterministic demo MCPB: test-outputs/reviewable-node.mcpb
SHA-256: 6948b641f88671717de7142ce075f21f9710621392b115a311eee05831fe5a1c

SkillGate MCPB scan completed
Entry point: server/index.js
Endpoint: https://api.example.invalid/v1
Secret reference: SERVICE_TOKEN

Start With Three Direct Scans

When you do not need the unified review packet, run the focused scanner directly:

skillgate github scan https://github.com/addyosmani/agent-skills/tree/main/skills --fail-on high
skillgate mcpb scan bundle.mcpb --fail-on high
skillgate scan .

Focused scans are useful for local audit loops, CI steps, and release checks. The recommended adoption path remains review preinstall first, then review summaries, policy enforcement, and baseline drift when the team is ready.

Connection Boundaries

The default path is local and upload-free:

• scan, skills validate, review preinstall with a local path, and `mcpb

scan` read local files and write results to the terminal or local output files.

• These local paths do not call GitHub, upload reports, install packages, start

servers, or execute scanned content.

Connections are explicit opt-ins:

• github scan and review preinstall with a GitHub URL make bounded requests

to GitHub to fetch the requested source for static review.

• GitHub Actions, SARIF uploads, Actions artifacts, and Code Scanning are

optional integrations used only when a repository owner enables a workflow.

Nothing in a local SkillGate invocation uploads findings automatically.

For a copyable first repository, use the [pre-install starter](examples/preinstall-starter/README.md) and its [review-only Action workflow](docs/starter-repository.md).

For concrete examples of how to interpret output, see the [public scan reports](docs/public-scan-reports/README.md).

For a guided walkthrough with a deterministic local input, see the [review sessions](docs/sessions/README.md).

For contribution and community paths, see [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), and the maintainer [repository settings checklist](docs/repository-settings.md).

Choose Your Use Case

| Use case | Start here | What you get | | --- | --- | --- | | Create a pre-install review packet | [skillgate review preinstall SOURCE](#start-with-pre-install-review) | Advisory source identity, capabilities, findings, validation, and reviewer next actions | | Scan a local skill or agent repo | [skillgate scan .](#1-scan-a-local-repository) | Nonblocking findings and capability inventory | | Validate an Agent Skill before publishing | [skillgate skills validate PATH](#1a-validate-an-agent-skill) | Deterministic structure and metadata checks | | Check a public GitHub skill repo before installing | [skillgate github scan URL](#2-scan-a-github-repository-before-installing) | Sparse remote scan with immutable ref manifest | | Block unapproved behavior in CI | [skillgate check . --policy skillgate.yaml](#3-enforce-policy-in-ci) | Policy violations, explanations, approvals, waivers | | Detect capability drift after review | [skillgate baseline create](#4-track-approved-baselines-and-drift) | Stable lockfile and SG010 drift findings | | Inspect an MCP bundle before installing | [skillgate mcpb scan bundle.mcpb](#5-scan-an-mcp-bundle-before-installing) | Static startup, file, endpoint, secret-reference, binary, and nested-archive review | | Inspect MCP registry metadata without installing | [skillgate mcp registry scan](#6-review-mcp-registry-metadata) | MCP tool, transport, package, and registry drift checks | | Build a review inventory | [skillgate inventory .](#7-build-a-capability-inventory) | Trust-boundary summary and filterable JSON | | Optionally export SARIF for GitHub code scanning | [--format sarif](#8-optionally-export-sarif-for-github-code-scanning) | Local SARIF output; upload is a separate opt-in | | Follow a guided review session | [Review sessions](docs/sessions/README.md) | Copy-pasteable pre-install, pre-merge, and approval workflows |

Install

Install the latest compatible GitHub release tag today:

python -m pip install "git+https://github.com/charliechenye/SkillGate.git@v0"
skillgate --version
skillgate --help

v0 is the moving compatibility tag for the latest compatible published 0.x release. For a concrete release tag, use the latest published version from GitHub Releases.

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

To inspect the latest release tag without installing:

git ls-remote --tags https://github.com/charliechenye/SkillGate.git "refs/tags/v*"

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. PyPI publication is deferred for 0.1.3. When it is intentionally revisited, the planned distribution name is openevalgate-skillgate:

pipx install openevalgate-skillgate
skillgate scan .

Also validate one-shot usage with:

uvx openevalgate-skillgate scan .

Experimental Node wrapper, after standalone GitHub Release assets are published:

npx --yes github:charliechenye/SkillGate#v0 -- scan .

This GitHub-first npx path does not require PyPI or npm registry publication. Bare npx skillgate scan . remains future work because it requires an npm package name and an intentional npm publication strategy. The root npm package is marked private until then. Details: [GitHub-first Node wrapper](docs/node-wrapper.md).

For contributor or source-checkout development:

uv sync --locked --group dev
uv run skillgate --version
uv run skillgate --help

1. Scan A Local Repository

Use 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 high

skillgate 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, MCP bundles, and MCP registry metadata. It reports rules SG001 through SG015, 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, MCP registry drift, MCPB startup/reference mismatches, and MCPB embedded artifacts that require review.

Useful follow-ups:

skillgate rules list
skillgate explain SG004

1A. Validate An Agent Skill

Use skills validate to check a skill before publishing or installing it. The validator reads only the skill file and local files; it never executes scripts, installs packages, calls a network, or uses an LLM:

skillgate skills validate path/to/my-skill
skillgate skills validate path/to/my-skill/SKILL.md --format json
skillgate skills validate skills/ --fail-on medium

It checks frontmatter, slug-style names, directory/name consistency, recommended metadata, declared tool breadth, local references, and executable files outside scripts/. Findings are advisory unless --fail-on is supplied. See the [Agent Skills validation guide](docs/skills-validation.md) for examples and limitations.

2. Scan A GitHub Repository Before Installing

Use 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.json

Remote 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](docs/github-preinstall-scan.md).

3. Enforce Policy In CI

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.json

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

• [Policy schema reference](docs/policy-schema.md)
• [Machine-readable JSON Schema](schemas/skillgate-policy.schema.json)
• [Schema-aware editor setup](docs/editor-setup.md)
• [Agent Skills validation](docs/skills-validation.md)
• [Example policy](skillgate.example.yaml)

4. Track Approved Baselines And Drift

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.yaml

Baseline 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.json

5. Scan An MCP Bundle Before Installing

Use mcpb scan to inspect a local MCP bundle before installing or executing its server:

skillgate mcpb scan bundle.mcpb
skillgate mcpb scan bundle.mcpb --format json
skillgate mcpb scan bundle.mcpb --format sarif --output skillgate-mcpb.sarif
skillgate mcpb scan bundle.mcpb --fail-on high
skillgate mcpb scan bundle.mcpb --manifest-output bundle-manifest.json

SkillGate does not execute bundle content, start MCP servers, install packages, or resolve dependencies. It safely inspects the ZIP-based bundle, parses the root manifest.json narrowly for startup-relevant fields, inventories members, selects first-party source for the existing rule engine, and reports deterministic text, JSON, or SARIF output.

Nested archives are retained and inventoried but are not recursively inspected. Embedded executables and shared libraries are identified for review; SkillGate does not declare them malicious. Manifest interpretation is intentionally narrow rather than complete MCPB schema validation. MCPB policy support is deferred until bundle-specific enforcement needs are clearer.

See [MCPB pre-install scanning](docs/mcpb-preinstall-scan.md) for the threat model, output fields, exit codes, limits, and examples.

6. Review MCP Registry Metadata

Use 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.sarif

Registry scanning rea

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: charliechenye
• Source: charliechenye/SkillGate
• License: MIT
• Homepage: https://chenyezhu.com/projects/skillgate/

Install and usage instructions live in the source repository linked above.