skill-guard

skill-guard

Python Library: Skill execution enforcement with breadcrumb-based verification

⚠️ IMPORTANT: This is a Python library, NOT a user-facing skill. You cannot invoke /skill-guard as a command. This package is used internally by Claude Code hooks to enforce skill execution patterns when users invoke skills.

Enforces skill execution patterns through breadcrumb tracking, ensuring skills follow their documented workflows and providing self-verification.

📚 What This Is

This is NOT a Claude skill - it's a Python library that hooks import:

# In your hooks:
from skill_guard import discover_all_skills, get_skill_config

What it does:

• Enforces skill execution patterns when users invoke skills (e.g., /package, /gto)
• Uses breadcrumb system to track skill execution steps
• Verifies skills follow their documented workflows
• Provides self-verification capabilities for skills
• skill_forced_eval hook: Enumerates all skills with YES/NO when slash command detected

What it does NOT do:

• ❌ You cannot invoke /skill-guard as a command

• ❌ There's no user-facing interface

• ❌ It's purely a backend library for hooks

• 🔒 Execution Enforcement: Ensures skills are invoked via their documented patterns

• 🍞 Breadcrumb Tracking: Monitors skill execution flow step-by-step with SQLite backend

• ✅ Self-Verification: Helps skills verify they're working as intended

• 📚 Knowledge Skill Exemption: Distinguishes execution skills (enforced) from reference skills (not enforced)

• 🔄 Declarative: Uses skill frontmatter and filesystem discovery as the source of truth

• ⚡ Fast: 3-20x faster with SQLite backend and caching

• 🗄️ SQLite Storage: Unified database with WAL mode for concurrent access

📦 Installation

For Hook Developers (Dev Mode)

skill-guard is a Python library dependency used by hooks. Install once:

cd P://packages/skill-guard
pip install -e .

Then import in your hooks:

from skill_guard import discover_all_skills, get_skill_config

For End Users

No action required. skill-guard is a backend library used by hooks, not a user-facing package. End users benefit from skill enforcement automatically without installing anything directly.

🚀 Quick Start

Usage in Hooks

# In your PreToolUse or UserPromptSubmit hooks:
from skill_guard import discover_all_skills, get_skill_config

# When a user invokes a skill (e.g., /package skill-guard):
# 1. UserPromptSubmit hook detects skill invocation
# 2. PreToolUse hook enforces execution pattern

# Get skill configuration for enforcement
config = get_skill_config("package", {})
print(f"First tool must be: {config.get('tools')}")  # e.g., ["Skill"]
print(f"Expected pattern: {config.get('pattern')}")    # e.g., call Skill first

How it works:

1. User types /package skill-guard
2. UserPromptSubmit hook detects skill invocation
3. PreToolUse hook enforces first tool must be Skill
4. Breadcrumb system tracks execution steps
5. Skill self-verifies it's following documented workflow

⚠️ Known Issues

GitHub Issue #16288: Plugin hooks not loaded from external hooks.json

Status: OPEN (as of 2026-05-21)

Problem: skill-guard defines hooks in hooks/hooks.json following the plugin specification, but Claude Code does not load hooks from external hooks.json files even when the plugin shows as "enabled" in the UI.

Workaround Implemented: skill-guard hooks are registered directly in P:/.claude/settings.json via a router pattern:

1. Router script: src/skill_guard/__lib/router.py dispatches to the appropriate hook module
2. Settings entries: Three compact registrations in ~/.claude/settings.json:
   • UserPromptSubmit → router.py UserPromptSubmit
   • PreToolUse → router.py PreToolUse
   • Stop → router.py Stop

Why this approach: A single router script minimizes settings.json footprint while providing centralized dispatch logic. When issue #16288 is resolved, the router can be removed and hooks will load automatically from hooks/hooks.json.

Related issues: #45296 (hooks.json deleted), #29767 (Stop hooks never execute), #18547 (hooks not loaded in VSCode extension)

---

🔧 Development (Windows)

Setup

# Navigate to package
cd P://packages/skill-guard

# Install as editable Python package
pip install -e .

# That's it! No junctions or Claude discovery needed.

Development Workflow

# Edit Python code
vim src/skill_guard/module.py

# Run tests
pytest