Agent Guardrails 🛡️

🇨🇳 中文文档

📖 Featured in: I audited my own AI agent system and found it full of holes — the security audit that spawned this 5-tool security suite. ⭐ audit-skills.sh is the comprehensive audit script at the heart of the article.

Your AI agent secretly bypasses your rules. This skill enforces them with code.

Works with: Claude Code | Clawdbot | Cursor | Any AI coding agent

Rules in markdown are suggestions. Code hooks are laws.

🚨 Stop production incidents before they happen — Born from real crashes, token leaks, and silent bypasses

The Problem

You spend hours building validation pipelines, scoring systems, and verification logic. Then your AI agent writes a "quick version" that bypasses all of it. Sound familiar?

Real Production Incidents (February 2026)

🔥 Server Crash: Bad config edit → service crash loop → server down all night
🔑 Token Leak: Notion token hardcoded in code, nearly pushed to public GitHub
🔄 Code Rewrite: Agent rewrote validated scoring logic instead of importing it, sent unverified predictions
🚀 Deployment Gap: Built new features but forgot to wire them into production, users got incomplete output

This isn't a prompting problem — it's an enforcement problem. More markdown rules won't fix it. You need mechanical enforcement that actually works.

Enforcement Hierarchy

Level	Method	Reliability
1	Code hooks (pre-commit, creation guards)	100%
2	Architectural constraints (import registries)	95%
3	Self-verification loops	80%
4	Prompt rules (AGENTS.md)	60-70%
5	Markdown documentation	40-50% ⚠️

This toolkit focuses on levels 1-2: the ones that actually work.

What's Included

Tool	Purpose
scripts/install.sh	One-command project setup
scripts/pre-create-check.sh	Lists existing modules before you create new files
scripts/post-create-validate.sh	Detects duplicate functions and missing imports
scripts/check-secrets.sh	Scans for hardcoded tokens/keys/passwords
assets/pre-commit-hook	Git hook that blocks bypass patterns + secrets
assets/registry-template.py	Template __init__.py for import enforcement
references/agents-md-template.md	Battle-tested AGENTS.md template
scripts/audit-skills.sh	⭐ Comprehensive security audit — scans all skills for gaps
references/enforcement-research.md	Full research on why code > prompts

Quick Start

For Claude Code:

git clone https://github.com/jzOcb/agent-guardrails ~/.claude/skills/agent-guardrails
cd your-project && bash ~/.claude/skills/agent-guardrails/scripts/install.sh .

For Clawdbot:

clawdhub install agent-guardrails

Manual:

bash /path/to/agent-guardrails/scripts/install.sh /path/to/your/project

📖 Claude Code detailed guide

This will:

• ✅ Install git pre-commit hook (blocks bypass patterns + hardcoded secrets)
• ✅ Create __init__.py registry template
• ✅ Copy check scripts to your project
• ✅ Add enforcement rules to your AGENTS.md

Usage

Before creating any new file:

bash scripts/pre-create-check.sh /path/to/project

Shows existing modules and functions. If it already exists, import it.

After creating/editing a file:

bash scripts/post-create-validate.sh /path/to/new_file.py

Catches duplicate functions, missing imports, and bypass patterns like "simplified version" or "temporary".

Secret scanning:

bash scripts/check-secrets.sh /path/to/project

How It Works

Pre-commit Hook

Automatically blocks commits containing:

• Bypass patterns: "simplified version", "quick version", "temporary", "TODO: integrate"
• Hardcoded secrets: API keys, tokens, passwords in source code

Pre-create Check

Before writing new code, the script shows you:

• All existing Python modules in the project
• All public functions (def declarations)
• The project's __init__.py registry (if it exists)
• SKILL.md contents (if it exists)

This makes it structurally difficult to "not notice" existing code.

Post-create Validation

After writing code, the script checks:

• Are there duplicate function names across files?
• Does the new file import from established modules?
• Does it contain bypass patterns?

Import Registry

Each project gets an __init__.py that explicitly lists validated functions:

# This is the ONLY approved interface for this project
from .core import validate_data, score_item, generate_report

# New scripts MUST import from here, not reimplement

Origin Story

Born from a real incident (2026-02-02): We built a complete decision engine for prediction market analysis — scoring system, rules parser, news verification, data source validation. Then the AI agent created a "quick scan" script that bypassed ALL of it, sending unverified recommendations. Hours of careful work, completely ignored.

The fix wasn't writing more rules. It was writing code that mechanically prevents the bypass.

Research

Based on research from:

• Anthropic's Claude Code Best Practices — "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic"
• Cursor's Scaling Agents — "Opus 4.5 tends to stop earlier and take shortcuts"
• Guardrails AI Framework
• NVIDIA NeMo Guardrails

Full research notes in references/enforcement-research.md.

For Clawdbot Users

This is a Clawdbot skill. Install via ClawdHub (coming soon):

clawdhub install agent-guardrails

Or clone directly:

git clone https://github.com/jzOcb/agent-guardrails.git

中文文档

完整中文文档见 references/SKILL_CN.md

🛡️ Part of the AI Agent Security Suite

Tool	What It Prevents
agent-guardrails	AI rewrites validated code, leaks secrets, bypasses standards
config-guard	AI writes malformed config, crashes gateway
upgrade-guard	Version upgrades break dependencies, no rollback
token-guard	Runaway token costs, budget overruns
process-guardian	Background processes die silently, no auto-recovery

📖 Read the full story: I audited my own AI agent system and found it full of holes

License

MIT — Use it, share it, make your agents behave.

🛡️ Part of the OpenClaw Security Suite

Guard	Purpose	Protects Against
agent-guardrails	Pre-commit hooks + secret detection	Code leaks, unsafe commits
config-guard	Config validation + auto-rollback	Gateway crashes from bad config
upgrade-guard	Safe upgrades + watchdog	Update failures, cascading breaks
token-guard	Usage monitoring + cost alerts	Budget overruns, runaway costs

📚 Full writeup: 4-Layer Defense System for AI Agents