{"id":"41e42c62-8022-4f63-98dc-a3ff6cc741a4","slug":"jzocb-agent-guardrails","kind":"skill","name":"agent-guardrails","summary":"Mechanical enforcement tools to prevent AI agents from bypassing established project standards.","owner":"jzOcb","repoUrl":"https://github.com/jzOcb/agent-guardrails","license":"MIT","licenseTier":"permissive","trust":"community","stars":15,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:16:41.818Z","logoUrl":"https://avatars.githubusercontent.com/u/258660657?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-agents","ai-guardrails","clawdbot-skill","devtools","enforcement","git-hooks","deployment-verification","mechanical-enforcement"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T09:01:01.201Z","sample":false,"url":"https://conduits.dev/tools/jzocb-agent-guardrails","language":"Shell","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Agent Guardrails 🛡️\n\n[🇨🇳 中文文档](./references/SKILL_CN.md)\n\n[![Claude Code Skill](https://img.shields.io/badge/Claude_Code-Skill-8A2BE2)](https://github.com/topics/claude-code-skill)\n[![Clawdbot Skill](https://img.shields.io/badge/Clawdbot-Skill-blue)](https://clawdhub.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Version](https://img.shields.io/badge/version-1.1.0-green.svg)](./VERSION)\n\n📖 **Featured in:** [I audited my own AI agent system and found it full of holes](https://x.com/xxx111god/status/2019455237048709336) — the security audit that spawned this 5-tool security suite. ⭐ **`audit-skills.sh`** is the comprehensive audit script at the heart of the article.\n\n## Your AI agent secretly bypasses your rules. This skill enforces them with code.\n\n**Works with:** Claude Code | Clawdbot | Cursor | Any AI coding agent\n\n> Rules in markdown are suggestions. Code hooks are laws.\n\n🚨 **Stop production incidents before they happen** — Born from real crashes, token leaks, and silent bypasses\n\n## The Problem\n\nYou 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?\n\n### Real Production Incidents (February 2026)\n\n**🔥 Server Crash:** Bad config edit → service crash loop → server down all night  \n**🔑 Token Leak:** Notion token hardcoded in code, nearly pushed to public GitHub  \n**🔄 Code Rewrite:** Agent rewrote validated scoring logic instead of importing it, sent unverified predictions  \n**🚀 Deployment Gap:** Built new features but forgot to wire them into production, users got incomplete output  \n\nThis isn't a prompting problem — it's an enforcement problem. More markdown rules won't fix it. You need mechanical enforcement that **actually works**.\n\n## Enforcement Hierarchy\n\n| Level | Method | Reliability |\n|-------|--------|-------------|\n| 1 | **Code hooks** (pre-commit, creation guards) | 100% |\n| 2 | **Architectural constraints** (import registries) | 95% |\n| 3 | **Self-verification loops** | 80% |\n| 4 | **Prompt rules** (AGENTS.md) | 60-70% |\n| 5 | **Markdown documentation** | 40-50% ⚠️ |\n\nThis toolkit focuses on levels 1-2: the ones that actually work.\n\n## What's Included\n\n| Tool | Purpose |\n|------|---------|\n| `scripts/install.sh` | One-command project setup |\n| `scripts/pre-create-check.sh` | Lists existing modules before you create new files |\n| `scripts/post-create-validate.sh` | Detects duplicate functions and missing imports |\n| `scripts/check-secrets.sh` | Scans for hardcoded tokens/keys/passwords |\n| `assets/pre-commit-hook` | Git hook that blocks bypass patterns + secrets |\n| `assets/registry-template.py` | Template `__init__.py` for import enforcement |\n| `references/agents-md-template.md` | Battle-tested AGENTS.md template |\n| `scripts/audit-skills.sh` | ⭐ Comprehensive security audit — scans all skills for gaps |\n| `references/enforcement-research.md` | Full research on why code > prompts |\n\n## Quick Start\n\n**For Claude Code:**\n```bash\ngit clone https://github.com/jzOcb/agent-guardrails ~/.claude/skills/agent-guardrails\ncd your-project && bash ~/.claude/skills/agent-guardrails/scripts/install.sh .\n```\n\n**For Clawdbot:**\n```bash\nclawdhub install agent-guardrails\n```\n\n**Manual:**\n```bash\nbash /path/to/agent-guardrails/scripts/install.sh /path/to/your/project\n```\n\n📖 [Claude Code detailed guide](./CLAUDE_CODE_INSTALL.md)\n\nThis will:\n- ✅ Install git pre-commit hook (blocks bypass patterns + hardcoded secrets)\n- ✅ Create `__init__.py` registry template  \n- ✅ Copy check scripts to your project\n- ✅ Add enforcement rules to your AGENTS.md\n\n## Usage\n\n### Before creating any new file:\n```bash\nbash scripts/pre-create-check.sh /path/to/project\n```\nShows existing modules and functions. If it already exists, **import it**.\n\n### After creating/editing a file:\n```bash\nbash scripts/post-create-validate.sh /path/to/new_file.py\n```\nCatches duplicate functions, missing imports, and bypass patterns like \"simplified version\" or \"temporary\".\n\n### Secret scanning:\n```bash\nbash scripts/check-secrets.sh /path/to/project\n```\n\n## How It Works\n\n### Pre-commit Hook\nAutomatically blocks commits containing:\n- Bypass patterns: `\"simplified version\"`, `\"quick version\"`, `\"temporary\"`, `\"TODO: integrate\"`\n- Hardcoded secrets: API keys, tokens, passwords in source code\n\n### Pre-create Check\nBefore writing new code, the script shows you:\n- All existing Python modules in the project\n- All public functions (`def` declarations)\n- The project's `__init__.py` registry (if it exists)\n- SKILL.md contents (if it exists)\n\nThis makes it **structurally difficult** to \"not notice\" existing code.\n\n### Post-create Validation\nAfter writing code, the script checks:\n- Are there duplicate function names across files?\n- Does the new file import from established modules?\n- Does it contain bypass patterns?\n\n### Import Registry\nEach project gets an `__init__.py` that explicitly lists validated functions:\n\n```python\n# This is the ONLY approved interface for this project\nfrom .core import validate_data, score_item, generate_report\n\n# New scripts MUST import from here, not reimplement\n```\n\n## Origin Story\n\nBorn 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.\n\nThe fix wasn't writing more rules. It was writing code that **mechanically prevents** the bypass.\n\n## Research\n\nBased on research from:\n- [Anthropic's Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) — *\"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic\"*\n- [Cursor's Scaling Agents](https://cursor.com/blog/scaling-agents) — *\"Opus 4.5 tends to stop earlier and take shortcuts\"*\n- [Guardrails AI Framework](https://www.guardrailsai.com/docs)\n- [NVIDIA NeMo Guardrails](https://github.com/NVIDIA-NeMo/Guardrails)\n\nFull research notes in `references/enforcement-research.md`.\n\n## For Clawdbot Users\n\nThis is a [Clawdbot](https://clawd.bot) skill. Install via ClawdHub (coming soon):\n```bash\nclawdhub install agent-guardrails\n```\n\nOr clone directly:\n```bash\ngit clone https://github.com/jzOcb/agent-guardrails.git\n```\n\n## 中文文档\n\n完整中文文档见 [`references/SKILL_CN.md`](references/SKILL_CN.md)\n\n## 🛡️ Part of the AI Agent Security Suite\n\n| Tool | What It Prevents |\n|------|-----------------|\n| **[agent-guardrails](https://github.com/jzOcb/agent-guardrails)** | AI rewrites validated code, leaks secrets, bypasses standards |\n| **[config-guard](https://github.com/jzOcb/config-guard)** | AI writes malformed config, crashes gateway |\n| **[upgrade-guard](https://github.com/jzOcb/upgrade-guard)** | Version upgrades break dependencies, no rollback |\n| **[token-guard](https://github.com/jzOcb/token-guard)** | Runaway token costs, budget overruns |\n| **[process-guardian](https://github.com/jzOcb/process-guardian)** | Background processes die silently, no auto-recovery |\n\n📖 **Read the full story:** [I audited my own AI agent system and found it full of holes](https://x.com/xxx111god/status/2019455237048709336)\n\n## License\n\nMIT — Use it, share it, make your agents behave.\n\n## 🛡️ Part of the OpenClaw Security Suite\n\n| Guard | Purpose | Protects Against |\n|-------|---------|------------------|\n| **[agent-guardrails](https://github.com/jzOcb/agent-guardrails)** | Pre-commit hooks + secret detection | Code leaks, unsafe commits |\n| **[config-guard](https://github.com/jzOcb/config-guard)** | Config validation + auto-rollback | Gateway crashes from bad config |\n| **[upgrade-guard](https://github.com/jzOcb/upgrade-guard)** | Safe upgrades + watchdog | Update failures, cascading breaks |\n| **[token-guard](https://github.com/jzOcb/token-guard)** | Usage monitoring + cost alerts | Budget overruns, runaway costs |\n\n📚 **Full writeup:** [4-Layer Defense System for AI Agents](https://x.com/xxx111god/status/2019096285853139083)\n"}