Claude-skill-registry agent-guardrails

Stop AI agents from secretly bypassing your rules. Mechanical enforcement with git hooks, secret detection, deployment verification, and import registries. Born from real production incidents: server crashes, token leaks, code rewrites. Works with Claude Code, Clawdbot, Cursor. Install once, enforce forever.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/agent-guardrails" ~/.claude/skills/majiayu000-claude-skill-registry-agent-guardrails && rm -rf "$T"

manifest: skills/data/agent-guardrails/SKILL.md

Agent Guardrails

Mechanical enforcement for AI agent project standards. Rules in markdown are suggestions. Code hooks are laws.

Quick Start

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

This installs the git pre-commit hook, creates a registry template, and copies check scripts into your project.

Enforcement Hierarchy

Code hooks (git pre-commit, pre/post-creation checks) — 100% reliable
Architectural constraints (registries, import enforcement) — 95% reliable
Self-verification loops (agent checks own work) — 80% reliable
Prompt rules (AGENTS.md, system prompts) — 60-70% reliable
Markdown rules — 40-50% reliable, degrades with context length

Tools Provided

Scripts

Script	When to Run	What It Does
`install.sh`	Once per project	Installs hooks and scaffolding
`pre-create-check.sh`	Before creating new `.py` files	Lists existing modules/functions to prevent reimplementation
`post-create-validate.sh`	After creating/editing `.py` files	Detects duplicates, missing imports, bypass patterns
`check-secrets.sh`	Before commits / on demand	Scans for hardcoded tokens, keys, passwords
`create-deployment-check.sh`	When setting up deployment verification	Creates .deployment-check.sh, checklist, and git hook template
`install-skill-feedback-loop.sh`	When setting up skill update automation	Creates detection, auto-commit, and git hook for skill updates

Assets

Asset	Purpose
`pre-commit-hook`	Ready-to-install git hook blocking bypass patterns and secrets
`registry-template.py`	Template `__init__.py` for project module registries

References

File	Contents
`enforcement-research.md`	Research on why code > prompts for enforcement
`agents-md-template.md`	Template AGENTS.md with mechanical enforcement rules
`deployment-verification-guide.md`	Full guide on preventing deployment gaps
`skill-update-feedback.md`	Meta-enforcement: automatic skill update feedback loop
`SKILL_CN.md`	Chinese translation of this document

Usage Workflow

Setting up a new project

bash scripts/install.sh /path/to/project

Before creating any new .py file

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

Review the output. If existing functions cover your needs, import them.

After creating/editing a .py file

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

Fix any warnings before proceeding.

Setting up deployment verification

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

This creates:

```
.deployment-check.sh
```
- Automated verification script
```
DEPLOYMENT-CHECKLIST.md
```
- Full deployment workflow
```
.git-hooks/pre-commit-deployment
```
- Git hook template

Then customize:

Add tests to
```
.deployment-check.sh
```
for your integration points
Document your flow in
```
DEPLOYMENT-CHECKLIST.md
```
Install the git hook

See

references/deployment-verification-guide.md

for full guide.

Adding to AGENTS.md

Copy the template from

references/agents-md-template.md

and adapt to your project.

中文文档 / Chinese Documentation

See

references/SKILL_CN.md

for the full Chinese translation of this skill.

Common Agent Failure Modes

1. Reimplementation (Bypass Pattern)

Symptom: Agent creates "quick version" instead of importing validated code. Enforcement:

pre-create-check.sh

post-create-validate.sh

+ git hook

2. Hardcoded Secrets

Symptom: Tokens/keys in code instead of env vars. Enforcement:

check-secrets.sh

+ git hook

3. Deployment Gap

Symptom: Built feature but forgot to wire it into production. Users don't receive benefit. Example: Updated

notify.py

but cron still calls old version. Enforcement:

.deployment-check.sh

+ git hook

This is the hardest to catch because:

Code runs fine when tested manually
Agent marks task "done" after writing code
Problem only surfaces when user complains

Solution: Mechanical end-to-end verification before allowing "done."

4. Skill Update Gap (META - NEW)

Symptom: Built enforcement improvement in project but forgot to update the skill itself. Example: Created deployment verification for Project A, but other projects don't benefit because skill wasn't updated. Enforcement:

install-skill-feedback-loop.sh

→ automatic detection + semi-automatic commit

This is a meta-failure mode because:

It's about enforcement improvements themselves
Without fix: improvements stay siloed
With fix: knowledge compounds automatically

Solution: Automatic detection of enforcement improvements with task creation and semi-automatic commits.

Key Principle

Don't add more markdown rules. Add mechanical enforcement. If an agent keeps bypassing a standard, don't write a stronger rule — write a hook that blocks it.

Corollary: If an agent keeps forgetting integration, don't remind it — make it mechanically verify before commit.