{"id":49118442,"url":"https://github.com/vaibhavtupe/skill-guard","last_synced_at":"2026-04-21T09:34:23.000Z","repository":{"id":342616835,"uuid":"1173323246","full_name":"vaibhavtupe/skill-guard","owner":"vaibhavtupe","description":"The quality gate for Agent Skills — validate, secure, conflict-detect, and test skills across their full lifecycle","archived":false,"fork":false,"pushed_at":"2026-04-11T05:33:22.000Z","size":281,"stargazers_count":3,"open_issues_count":8,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-11T06:18:06.647Z","etag":null,"topics":["agent-skills","ai-agents","cli","llm","openai","python","quality-gate","skill-guard"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaibhavtupe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T08:38:42.000Z","updated_at":"2026-04-11T05:33:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vaibhavtupe/skill-guard","commit_stats":null,"previous_names":["vaibhavtupe/skill-guard"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/vaibhavtupe/skill-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavtupe%2Fskill-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavtupe%2Fskill-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavtupe%2Fskill-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavtupe%2Fskill-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaibhavtupe","download_url":"https://codeload.github.com/vaibhavtupe/skill-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavtupe%2Fskill-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32085653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","cli","llm","openai","python","quality-gate","skill-guard"],"created_at":"2026-04-21T09:34:22.229Z","updated_at":"2026-04-21T09:34:22.977Z","avatar_url":"https://github.com/vaibhavtupe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# skill-guard\n\n**The quality gate for Agent Skills.**\n\n[![PyPI version](https://badge.fury.io/py/skill-guard.svg)](https://badge.fury.io/py/skill-guard)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n\nskill-guard is a CLI tool that validates, secures, and checks [Agent Skills](https://agentskills.io), with the default workflow centered on pre-merge repository gates.\n\n## The Problem\n\nAgent Skills are powerful. They're also ungoverned. As soon as more than one person contributes skills to a shared agent, things break in hard-to-diagnose ways:\n\n- A new skill's description overlaps with an existing one → agent picks the wrong skill half the time\n- Skills with dangerous scripts get merged because nobody reviewed the `scripts/` directory\n- Nobody knows what skills are installed, who owns them, or whether they still work\n- A skill passes every test in isolation but fails when the real agent uses it with 25 other skills loaded\n\nskill-guard is the quality gate that catches these problems before they reach production.\n\n## What It Does\n\n```\nONBOARDING (pre-merge, in CI):\n  skill-guard validate   → format compliance + quality scoring\n  skill-guard secure     → scan for dangerous patterns  \n  skill-guard conflict   → detect trigger overlap with existing skills\n  skill-guard test       → optional live evals against an OpenAI-compatible endpoint. For CI, prefer custom_hook + --workspace; directory_copy and git_push are secondary workflows.\n  skill-guard check      → runs validate + secure + conflict as a single gate. Agent evals run if --endpoint is configured.\n\nOPTIONAL / NON-DEFAULT:\n  skill-guard monitor    → re-run evals and lifecycle checks on a schedule. Run via cron or CI. No built-in scheduler.\n  skill-guard catalog    → maintain a YAML skill catalog. Approval workflow is not implemented in the CLI.\n```\n\n## Quick Start\n\n```bash\npip install skill-guard\n\n# Initialize in your skills repo\nskill-guard init\n\n# Run the default gate\nskill-guard check ./skills/my-skill/ --against ./skills/\n```\n\nIf you only learn one command, learn `check`. It is the default pre-merge workflow and the command the GitHub Actions path is built around.\n\n### Advanced / Secondary Commands\n\nUse these when you need to inspect one part of the gate in isolation or run non-default workflows:\n\n```bash\n# Format and metadata quality only\nskill-guard validate ./skills/my-skill/\n\n# Security only\nskill-guard secure ./skills/my-skill/\nskill-guard secure ./skills/my-skill/ --skip-references\n\n# Conflict detection only\nskill-guard conflict ./skills/my-skill/ --against ./skills/\n```\n\n### Optional Live Eval Setup\n\n```yaml\n# skill-guard.yaml\n\ntest:\n  endpoint: http://localhost:8000\n  model: gpt-4.1\n  workspace_dir: ./eval-workspace\n  injection:\n    method: custom_hook\n    pre_test_hook: hooks/pre-test.sh\n    post_test_hook: hooks/post-test.sh\n  reload_health_check_path: /health\n\n# Secondary workflows remain available for specialized setups:\n# - directory_copy into a mounted skills directory\n# - git_push into a repo your agent syncs from\n# test:\n#   endpoint: http://localhost:8000\n#   model: gpt-4.1\n#   injection:\n#     method: git_push\n#     git_repo_path: /path/to/agent-repo\n#     git_remote: origin\n#     git_branch: main\n#     git_skills_dir: skills\n```\n\n### Example Output\n\n```\n$ skill-guard validate ./skills/my-skill/\n\n skill-guard validate — my-skill\n┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Check                     ┃ Result                                           ┃\n┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩\n│ skill_md_exists           │ ✅ SKILL.md found                                │\n│ valid_yaml_frontmatter    │ ✅ Valid YAML frontmatter                        │\n│ name_field_present        │ ✅ name: my-skill                                │\n│ description_field_present │ ✅ description field present                     │\n│ directory_name_matches    │ ✅ Directory name matches skill name             │\n│ description_trigger_hint  │ ✅ Description contains trigger hint ('Use when')│\n│ no_broken_body_paths      │ ✅ No broken relative paths in SKILL.md body     │\n│ evals_directory_exists    │ ⚠️ No evals/ directory found                     │\n│                           │ → Create evals/evals.json or evals/config.yaml   │\n│ metadata_has_author       │ ✅ author: my-team                               │\n│ metadata_has_version      │ ✅ version: 1.0                                  │\n└───────────────────────────┴──────────────────────────────────────────────────┘\nScore: 97/100 | Grade: A | Blockers: 0 | Warnings: 1\n```\n\n## Installation\n\n## Prerequisites\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | 3.11+ | Required. 3.12 and 3.13 tested. |\n| pip | any recent | Bundled with Python |\n| typer | ≥0.13.0 | Installed automatically |\n| Agent endpoint | — | Required only for `skill-guard test` (OpenAI-compatible API) |\n\n\u003e **Note:** `skill-guard validate`, `secure`, `conflict`, `init`, `catalog`, and `check` work fully offline — no agent or API key needed.\n\nThe default offline path is already useful on its own: `validate` catches structure and metadata problems, `secure` catches risky patterns with remediation hints, `conflict` flags overlapping triggers, and `check` combines those static gates into one pre-merge decision.\n\n## Installation\n\n```bash\n# Core (static analysis — no agent required)\npip install skill-guard\n\n# Optional embeddings support\npip install skill-guard[embeddings]\n\n# Optional LLM-based conflict detection\npip install skill-guard[llm]\n```\n\n## Conflict Detection Modes\n\n```bash\n# TF-IDF (default)\nskill-guard conflict ./skills/my-skill/ --against ./skills/ --method tfidf\n\n# Embeddings-based overlap detection\nskill-guard conflict ./skills/my-skill/ --against ./skills/ --method embeddings\n\n# Choose a different embeddings model\nskill-guard conflict ./skills/my-skill/ --against ./skills/ --method embeddings --model all-MiniLM-L12-v2\n\n# Offline embeddings (local model only; no downloads)\nskill-guard conflict ./skills/my-skill/ --against ./skills/ --method embeddings \\\n  --model-path /models/all-MiniLM-L6-v2 --offline\n\n# LLM-based overlap detection\nexport OPENAI_API_KEY=...\nskill-guard conflict ./skills/my-skill/ --against ./skills/ --method llm\n```\n\n`embeddings` uses the `all-MiniLM-L6-v2` sentence-transformers model by default (override with `--model`, `--model-path`, or `conflict.embeddings_model`/`conflict.embeddings_model_path`) and caches downloads under `conflict.embeddings_cache_dir` (default `.skill-guard-cache/embeddings/`). On first download, it prints a \"Downloading model...\" message to stderr. Use `--offline` to require a local/cached model and skip downloads. `llm` uses the OpenAI Chat API with `gpt-4o-mini` by default.\n\n### Ignoring known conflicts\n\nAdd `conflict_ignore` to your SKILL.md frontmatter to skip comparisons against specific skills:\n\n```yaml\n---\nname: my-skill\ndescription: \"Use when ...\"\nconflict_ignore:\n  - legacy-skill\n  - skills/legacy-skill/SKILL.md\n---\n```\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [End-to-End Integration Guide](docs/integration-guide.md) ← start here for real agent setup\n- [Writing Evals](docs/eval-authoring-guide.md)\n- [Hook Scripts](docs/hooks-guide.md)\n- [CI/CD Integration](docs/ci-integration.md)\n- [Configuration Reference](docs/configuration-reference.md)\n- [Automation Policy](docs/automation-policy.md)\n- [Release Gate Checklist](docs/release-gate.md)\n- [Roadmap](ROADMAP.md)\n\n## Anthropic Spec Validation\n\n`skill-guard validate` includes Anthropic AgentSkills spec compliance checks by default. Set `validate.anthropic_spec: false` in `skill-guard.yaml` if you need to disable those additional findings.\n\n## Exit Codes\n\n- `0`: success\n- `1`: validation/security failures\n- `2`: warnings only (when `fail_on_warning` is false)\n- `3`: config error\n- `4`: parse error\n- `5`: hook script failure\n- `6`: health check timeout\n\n## Trust States\n\nCommand output now uses one shared trust-state vocabulary alongside CI-oriented status fields:\n\n- `clean`: no action required\n- `warning`: non-blocking issue; review or tighten before merge if needed\n- `exception`: intentional exception or suppression is present; reviewable, not silent\n- `needs_review`: no blocking failure, but a human still needs to inspect the result\n- `blocking`: the command found a merge-stopping problem\n\n## Pre-commit\n\nUse `pre-commit` to enforce checks before skill changes land:\n\n```yaml\nrepos:\n  - repo: https://github.com/vaibhavtupe/skill-guard\n    rev: v0.6.0\n    hooks:\n      - id: skill-guard-validate\n      - id: skill-guard-secure\n      - id: skill-guard-check\n```\n\nThese hooks run against changed `SKILL.md` files, deduplicate by skill root, and then execute the corresponding `skill-guard` command for each affected skill.\n\n## Templates\n\nUse `skill-guard init --template base` to scaffold a new skill, or `skill-guard init --list-templates` to see the available scaffolds. Generated templates include `SKILL.md`, `evals/evals.json`, `references/`, `scripts/`, and `assets/` so they validate immediately.\n\n## GitHub Actions\n\n```yaml\nname: skill-guard PR Gate\n\non:\n  pull_request:\n    paths:\n      - \"skills/**\"\n\njobs:\n  skill-guard:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with:\n          python-version: \"3.12\"\n      - run: python -m pip install skill-guard\n      - run: |\n          skill-guard check skills/ \\\n            --changed \\\n            --base-ref \"${{ github.event.pull_request.base.sha }}\" \\\n            --head-ref \"${{ github.sha }}\" \\\n            --format md \u003e skill-guard-summary.md\n```\n\nSee [docs/ci-integration.md](docs/ci-integration.md) for the canonical workflow, JSON + markdown artifact strategy, and the checked-in example at [.github/workflows/skill-guard-pr-gate.yml](.github/workflows/skill-guard-pr-gate.yml).\n\n## What skill-guard Does NOT Do\n\n- Does **not** replace [Anthropic's skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) for writing skills\n- Does **not** host or serve skills — skills live in your repo\n- Does **not** modify skills — it reports issues, authors fix them\n- Does **not** require a database or server — the catalog is a YAML file in your repo\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). We welcome contributions of all kinds.\n\nFor planning and release discipline:\n- `ROADMAP.md` is the canonical scope source\n- `docs/automation-policy.md` defines PM ↔ Dev workflow\n- `docs/release-gate.md` is the required pre-release checklist\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaibhavtupe%2Fskill-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaibhavtupe%2Fskill-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaibhavtupe%2Fskill-guard/lists"}