Guardrails Skill
adewale/guardrails-skill
Gates de qualidade acionáveis no ciclo de vida do agent de código Claude
Ver no GitHubSkill que implementa gates de qualidade no ciclo de vida de agentes de código Claude, movendo validações de espaço de prompt para espaço de ambiente. Define comportamentos através de lifecycle hooks, circuit breaker e proteções de configuração que bloqueiam o progresso até que as checagens passem, fornecendo feedback inequívoco ao agente sem custo de tokens.
Instalação
npx convez-ai adewale/guardrails-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validação contínua em agentes de código
- Prevenção de thrashing com circuit breaker
- Proteção de configurações de teste contra enfraquecimento
- Verificação de integração em commits
- Escalação diagnóstica com ferramentas estruturadas
Veredito

Solução madura e bem pensada que transfere constraints de prompt para ambiente, oferecendo feedback ao agente via falhas de build em vez de instruções prosaicas. Compatível com múltiplos agentes e com mecanismos sofisticados como circuit breaker e persistência de lições aprendidas.
README
A tradução para o português deste README ainda está na fila.
Guardrails Skill
Quality gates wired into the agent lifecycle. Not guidance the agent might follow — checks that block progress until they pass.
The Idea
Most coding-agent instructions live in prompt space: prose rules the agent might follow, might not. This skill moves constraints into environment space wherever possible. A lint rule that fails the build in 20ms gives the agent unambiguous feedback at zero token cost. A prose instruction competes for attention with everything else in the context window. The skill focuses on the behaviors a coding agent wouldn't exhibit without being told, and trusts the agent's training for everything else (what linting is, how to write a unit test, which formatter to use).
The novel behaviors:
- Lifecycle hooks —
script/test_fastruns on every stop,script/testruns on every commit. The agent can't declare success or commit code until checks pass. - Circuit breaker — After 2 failed attempts at the same fix, the agent must build a diagnostic tool or switch to a structured notation before retrying. Stops thrashing.
- Config protection — The agent can't weaken its own tests to make them pass.
- Integration check — At commit time, verify new code is reachable (wired in), not just correct (tests pass).
- Diagnostic escalation — A catalog of tools and notations for when the agent is stuck, plus proactive recognition of problem shapes that benefit from scaffolding.
- Lessons learned — Knowledge persisted across sessions so the agent doesn't repeat mistakes.
Install
npx skills add adewale/guardrails-skill
Skills appear on skills.sh automatically after users install the repo with the skills CLI. Install counts and leaderboard rankings come from anonymous CLI telemetry; opt out with DISABLE_TELEMETRY=1. The repo page customization in skills.sh.json is picked up after the repository is seen by telemetry and the cache refreshes.
Agent compatibility
The installable skill directory is skills/guardrails. It uses the Agent Skills SKILL.md format and is configured for Codex, OpenCode, Pi, Gemini CLI, and Claude Code.
Codex, OpenCode, Pi, and Gemini CLI can load the Guardrails skill instructions. Claude Code plugin installs additionally wire the bundled lifecycle hooks. In other agents, treat the hooks as an explicit checklist unless you add native hooks/extensions for that host.
| Agent/client | Install or use |
|---|---|
| Codex | cp -R skills/guardrails ~/.codex/skills/guardrails |
| OpenCode | cp -R skills/guardrails ~/.config/opencode/skills/guardrails or use .opencode/skills/guardrails in a project |
| Pi | pi install https://github.com/adewale/guardrails-skill or pi --skill skills/guardrails |
| Gemini CLI | gemini skills install https://github.com/adewale/guardrails-skill --path skills/guardrails or copy to .gemini/skills/guardrails |
| Claude Code | npx skills add adewale/guardrails-skill or copy to .claude/skills/guardrails |
Or as a Claude Code plugin:
/plugin marketplace add adewale/guardrails-skill
/plugin install guardrails@guardrails-skill
Or clone into your Claude Code skills directory:
# Personal (all projects)
git clone https://github.com/adewale/guardrails-skill ~/.claude/skills/guardrails
# Or project-level (one project only)
git clone https://github.com/adewale/guardrails-skill .claude/skills/guardrails
Browse the repo on skills.sh, or open the guardrails skill page.
Structure
guardrails-skill/
├── .claude-plugin/
│ ├── plugin.json Plugin manifest
│ ├── marketplace.json Marketplace catalog
│ └── hooks/
│ └── hooks.json Lifecycle hooks (plugin path)
├── skills/
│ └── guardrails/
│ ├── SKILL.md ← Agent reads this (~200 lines)
│ ├── references/
│ │ ├── tool-building.md Diagnostic tools, notations, worked examples
│ │ └── language-defaults.md Tool selection table by ecosystem
│ └── assets/
│ └── notation-templates/
│ └── reproduction-script.sh Bash scaffold for repro scripts
├── CLAUDE.md
├── LICENSE
└── README.md
SKILL.md is the core — everything the agent needs to know about when checks run and what
to do when stuck. The references are loaded on demand: tool-building.md when the circuit
breaker fires, language-defaults.md when writing test scripts for an unfamiliar ecosystem.
Hooks
Hooks are registered automatically on installation — no manual setup needed. Both installation paths (skill and plugin) wire the same four hooks:
| Hook | Event | Type | What it does |
|---|---|---|---|
| Discovery | SessionStart | agent | Inspects project for existing config, test runners, conventions |
| Stop check | Stop | prompt | Verifies fast check ran, tests match code changes, circuit breaker respected |
| Commit gate | PreToolUse (Bash) | prompt | Blocks git commit until full suite passes, secrets scanned, code reachable |
| Config protection | PreToolUse (Edit/Write) | prompt | Blocks edits to lint/test/CI config — agent must propose changes to user |
- Skill install (
npx skills addor git clone to.claude/skills/): hooks are declared in the SKILL.md frontmatter. - Plugin install (
/plugin install): hooks are declared in.claude-plugin/hooks/hooks.json.
View registered hooks in a session with /hooks.
Verifying Installation
After installing, start a new Claude Code session in a project with existing config (e.g., a Node project with package.json, eslint, tests).
1. Check hook registration. Run /hooks in the session. You should see four hooks
labeled with their source ([Skill] or [Plugin] depending on install method):
SessionStart, Stop, PreToolUse (Bash), and PreToolUse (Edit|Write).
2. Confirm discovery fires. On session start the status line should show "Guardrails: discovering project..." and the agent should report its findings (git baseline, detected test runner, project type) before you ask anything.
3. Test the stop check. Ask the agent to make a small code change. When it finishes, the status line should show "Guardrails: stop check..." — the agent should run the fast check (lint, format, types, unit tests) before returning control.
4. Test the commit gate. Ask the agent to commit. The status line should show "Guardrails: commit gate..." and the agent should run the full suite, scan for secrets, and verify new code is reachable before committing.
5. Test config protection. Ask the agent to relax an eslint rule or disable a test. The status line should show "Guardrails: config protection..." and the agent should propose the change to you instead of editing the config directly.
If any hook is missing from /hooks, restart the session — hooks are captured at startup.
Testing This Skill
Shared-harness evals live in evals/shared-benchmark.json and are run with the
standalone Skill Eval Harness:
uv tool install git+https://github.com/adewale/skill-eval-harness.git@v0.3.0
skill-benchmark validate evals/shared-benchmark.json
Key scenarios to test:
- SessionStart: Does the agent discover existing config and conventions before writing code? Does it create test scripts if they're missing?
- Stop evidence: When blocking, does the agent cite the fast-check command/status, production files changed, matching test changes or non-production reason, and next action?
- Circuit breaker: When the agent fails twice, does it build a diagnostic (state transition table, reproduction script, data flow diagram) instead of trying a third direct fix?
- Proactive recognition: Does the agent build a call site inventory before modifying a widely-used function? A decision matrix before implementing complex conditionals?
- High-risk gating: Does the agent stop and ask before destructive operations (DROP TABLE, data migrations, deployment actions)?
- Integration check: Does the agent verify new code is wired in (routes registered, modules imported) at commit time?
References
- Matt Holden, "Guardrail Coding" (February 2026) — The guidance vs. guardrails distinction (prompt space vs. environment space) that shaped this skill's focus on enforcement hooks over prose instructions. Also: "Onboarding AI Agents" for the quality gates concept, and "Markdown Coding."
- Cai et al., "Large Language Models as Tool Makers" (2023) — LLM creates reusable Python tools; cheaper LLM uses them. Influenced the agent tool library and diagnostic-tool-graduation concepts.
- Wang et al., "Voyager" (2023) — Minecraft agent with ever-growing skill library. Influenced the persistent tool accumulation pattern.
- Yang et al., "SWE-agent" (2024) — Custom Agent-Computer Interface for coding agents. Influenced the reproduction-script-first diagnostic approach.