Skip to main content

🛡️ SkillGuard

The Static Security Scanner, Linter, and Quality Gate for AI Agent Skills (SKILL.md).

Python 3.10+ License Tests Zero Dependencies

Works seamlessly across Claude Code, Cursor, Google Antigravity, OpenAI Codex, and LangChain DeepAgents.


⚡ The Problem: Why Unchecked Agent Skills Fail

As autonomous coding agents adopt the SKILL.md paradigm, developers are writing, sharing, and auto-generating hundreds of skill packs. However, empirical research reveals severe pitfalls:

  • Negative Transfer (−1.3pp to −11.5pp): Skills written without strict structural bounds and actionable specificity actually degrade agent performance by 25% to 47% (arXiv:2602.12670, arXiv:2605.23899).
  • Security & Destructive Operations: Unhedged skills instruct agents to execute permanent deletions (rm -rf, DROP TABLE), invite external users, or forward data outside workspace boundaries.
  • Prompt Injection Compliance: Agents following instructions inside untrusted tool/email outputs treat injected text as commands without scope guards (arXiv:2604.05172, arXiv:2605.12015).
  • Routing Collisions & Context Bloat: Overlapping skill descriptions confuse the LLM router, while skills over 1,600 words dilute context and collapse lift from +19.0pp to +10.1pp.

SkillGuard is the "ESLint + Snyk" for Agent Skills. It catches defects, security vulnerabilities, routing collisions, and token bloat in milliseconds—before runtime.


🚀 Quick Start

Installation

pip install skillguard-lint

(Zero dependencies by default. Runs anywhere on Python 3.10+ using only the Python standard library).

1. Lint and Check Skills

Scan an individual SKILL.md or a directory of skills:

skillguard check ./skills/
# Or use the fast alias:
skg check ./skills/

2. Security & Safety Audit

Audit specifically for destructive actions, credential leakage, and prompt injection patterns:

skillguard audit ./skills/

Smart Negation Detection: SkillGuard understands English grammar and negative constraints. Unlike naive regex scripts, defensive sentences like Never run rm -rf on the build directory or scope-guard bullets like - Avoid dropping tables will never trigger false positives.

3. Detect Routing Collisions & Overlaps

Identify duplicate skills, trigger collisions, and excessive library accumulation:

# Pure-Python Lexical & Trigger Overlap (Default, <10ms, zero-dependency)
skillguard dedupe ./skills/

# Optional: Dense Vector Semantic Similarity (requires sentence-transformers)
skillguard dedupe ./skills/ --semantic

(To use dense vector semantic embeddings, install the optional extra: pip install "skillguard-lint[semantic]").

4. Scaffold a New Production-Ready Skill

Generate a clean, gold-standard, 100% compliant skill pack:

skillguard init git-conflict-resolver --description "Resolve git merge conflicts cleanly"

5. Inspect Library Token Footprint

skillguard stats ./skills/

🤖 GitHub Actions CI/CD Integration

Prevent broken or insecure agent skills from merging into your repository. Add this workflow to .github/workflows/skill-audit.yml:

name: Skill Quality & Security Audit

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  audit-skills:
    name: Audit Agent Skills
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install skillguard-lint
      - run: skillguard check ./skills/ --format github

When run in GitHub Actions with --format github, SkillGuard automatically posts inline annotations directly on your pull request diffs!


📋 Diagnostic Rule Catalog

Run skillguard rules to inspect the full catalog:

Code Category Severity Name Description
SF001 Structure ERROR missing-frontmatter Missing YAML frontmatter block (--- ... ---)
SF002 Structure ERROR missing-required-metadata Frontmatter missing required name or description
SF003 Structure WARNING nonstandard-metadata-key Non-standard metadata key in YAML frontmatter
SF004 Quality WARNING missing-trigger-clause Description does not start triggers with "Use when..."
SF005 Structure ERROR missing-pipeline-section Missing ## Pipeline or ## Procedure ordered steps
SF006 Safety ERROR missing-scope-guard Missing ## Scope guard boundary definitions
SF007 Quality WARNING missing-not-in-scope Missing ## Not in scope boundary section
SF008 Bloat WARNING body-too-long Body exceeds 1,600 words (~2,000 tokens)
SF009 Quality WARNING body-too-short Body is under 30 words (lacks actionable detail)
SF101 Security ERROR destructive-command Irreversible deletion (rm -rf, os.remove, Path.unlink)
SF102 Security ERROR destructive-database-action Destructive database op (DROP TABLE, TRUNCATE, DELETE FROM)
SF103 Security ERROR data-exfiltration-risk Unauthorized external sending or auto-forwarding
SF104 Security ERROR permission-escalation Public sharing (anyone-with-link, setAdmin)
SF105 Security ERROR prompt-injection-pattern Instruction override (ignore previous instructions, verifier tamper)
SF106 Security ERROR secret-credential-probing Harvesting environment variables or probing localhost
SF107 Security ERROR dangerous-sidecar-file Unsafe pattern detected in scripts/ or references/
SF201 Portability WARNING absolute-path-leakage Absolute filesystem path (C:\..., /home/...) in body
SF202 Portability WARNING hash-or-uuid-literal Hardcoded UUID or hash literal (overfitted lookup)
SF301 Library WARNING skill-description-collision High trigger overlap (>55%) between skill descriptions
SF302 Library WARNING library-size-exceeded Library exceeds 8 active skills (context dilution risk)
SF303 Library WARNING domain-duplicate-skills Multiple active skills competing in the same domain

⚙️ ESLint-Style Rule Suppression

SkillGuard supports granular inline directives identical to ESLint:

1. Disable Next Line

<!-- skillguard-disable-next-line SF101 -->
Run rm -rf /tmp/test-cache to reset local test state.

2. Disable Multi-Line Block

<!-- skillguard-disable SF101, SF102 -->
Execute shutil.rmtree(staging_dir)
Run DROP TABLE staging_users;
<!-- skillguard-enable SF101, SF102 -->

3. File-Level Suppression

<!-- skillguard: ignore SF008, SF201 -->

4. CLI Suppression

skillguard check ./skills/ --ignore SF008,SF201

📚 Verified Research Foundations

SkillGuard's rules, heuristics, and thresholds are derived directly from published peer-reviewed AI agent benchmarks:

  1. SkillsBench (arXiv:2602.12670):
    Xiangyi Li, Wenbo Chen, Yimin Liu, et al.
    Key finding: Uncurated self-generated skills deliver −1.3pp average lift (down to −11.5pp), while structured curated skills achieve +16.6pp. Focused modular skill registers consistently outperform bloated documentation packs.
  2. ClawsBench (arXiv:2604.05172):
    Evaluating Capability and Safety of LLM Productivity Agents in Simulated Workspaces.
    Key finding: Adding domain skills without safety guardrails increases an agent's Unsafe Action Rate from 23% to 48%. Introducing an explicit Scope Guard instruction layer cuts unsafe actions by −21.9pp to −27.5pp without hurting task capability.
  3. SkillFlow (arXiv:2604.17308):
    Benchmarking Lifelong Skill Discovery and Evolution for Autonomous Agents.
    Key finding: Consolidating into 1 repeatedly-refined skill per domain beats accumulating multiple sibling skills (+19.0pp vs +10.1pp). Active library sizes beyond 8 skills lead to catastrophic routing interference.
  4. From Raw Experience to Skill Consumption (arXiv:2605.23899):
    Zisu Huang, Jingwen Xu, Yifan Yang, et al.
    Key finding: Measures 25% to 47% negative transfer in model-generated skills lacking procedural grounding and negative scoping (## Not in scope).
  5. SkillSafetyBench (arXiv:2605.12015):
    Chang Jin, An Wang, Zeming Wei, et al.
    Key finding: Sidecar reference files and helper scripts are major attack vectors for prompt injection and sandbox escape. Validating scripts/ and references/ sidecars is essential for agent safety.

🏛️ Core Invariants

  • Zero Network, Stdlib Only: Default runtime makes zero HTTP/network calls and has no external dependencies.
  • Sub-100ms Execution: Built in pure Python for instantaneous execution in git pre-commit hooks and local terminals.
  • Non-Destructive: Safe to execute across any private codebase or workspace.

📜 License

Apache-2.0 — Open source and enterprise ready.

Metadata

Release files for skillguard-lint 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for skillguard-lint 0.1.0
File Size Uploaded Provenance Actions
skillguard_lint-0.1.0.tar.gz 39.8 kB Without provenance Details for skillguard_lint-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for skillguard-lint 0.1.0
File Interpreter ABI Platform Actions
skillguard_lint-0.1.0-py3-none-any.whl Python 3 none any Details for skillguard_lint-0.1.0-py3-none-any.whl

Total release size: 67.3 kB

Release files / skillguard_lint-0.1.0.tar.gz

Download URL skillguard_lint-0.1.0.tar.gz
Size 39.8 kB
Tags Source
SHA-256 checksum
How to use checksums
49d81df730e731a26378ddbea6b6927939415a0b2bed7c49f08152529cee71d9
BLAKE2b-256 checksum
How to use checksums
1a5bcffec33c08e47ba438087edeff56321e19009ca21b4f071a2d89e7a36bde
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

Release files / skillguard_lint-0.1.0-py3-none-any.whl

Download URL skillguard_lint-0.1.0-py3-none-any.whl
Size 27.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
71cd0731192422ca9e198cf94dd435dbf44facc8a282a8abb8ca85d3c5bf068e
BLAKE2b-256 checksum
How to use checksums
9ca3858ece4358b4d0ae40e7841bc6093bb35ec25073bbadf4f5fc03ca320267
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

Security for skillguard-lint 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page