Pi is the open-source self-extensible coding agent built by Mario Zechner. It's an MIT-licensed CLI that treats skills as the primary mechanism for extending the agent rather than a bolt-on. Most agents have skills support layered onto an existing tool design. Pi was built around the Agent Skills standard from the start.
For authorization work, that posture matters. The hard part of writing policies isn't the YAML. It's the spec. "Editors can update posts in their own department" hides three or four implicit decisions. What is a department. Does an editor inherit access from a parent department. What about an editor who moves teams mid-edit. Most authorization bugs trace back to a missing answer on a question like that. Pi's skill-first design surfaces those questions cleanly, and the Cerbos policy skill registers as a slash command that runs the same way it runs in any other compliant agent.
This guide walks through installing the skill, what a Pi session looks like, how validation runs against the real compiler, and what Pi's skill-first design adds to the workflow.
Installing the policy skill in Pi
Pi reads skills from .pi/skills/ and .agents/skills/ for project scope, and ~/.pi/agent/skills/ and ~/.agents/skills/ for global. The cross-agent installer puts them in the right place.
npx skills add cerbos/skills --skill cerbos-policy -a pi
The skill registers as a slash command. Run /skill:cerbos-policy inside Pi to invoke it explicitly, with any text after the name passed as the user input. Pi also supports description-based auto-loading, so describing a permission problem in plain English will pick the skill up.
There's also a --skill <path> flag for one-off use without committing the skill to the repo, and skills can be declared in a project's package.json under a pi.skills entry. The skill source is in our skills repo for inspection before installing.
A typical Pi policy session
Open Pi against the repo where the Cerbos policies should live. Describe the access model in the same words you'd put in a design doc.
"Knowledge base. Authors write articles. Reviewers approve articles before publication. Subscribers read published articles. Subscribers in the premium tier read paywalled content. Authors can edit their own drafts but not published articles."
The skill doesn't start writing YAML. It asks pointed questions first. Can a reviewer also be an author on a different article. What happens to a published article when its author leaves. Are paywalled articles searchable for non-premium subscribers. Each question closes a gap in the spec that would otherwise turn into a bug six months later. Vague requirements are where authorization bugs live.
Once the spec is confirmed, the skill produces the full bundle in a single pass. Schemas under _schemas/, derived roles, shared variables, resource policies, and a testdata/ directory with fixtures and a test suite. Each rule has a condition. No wildcard actions. Explicit deny paths.
A note on using AI to write security policies
The Cerbos policy skill is a tool to help you get started. It is not a replacement for human review. Every policy the skill generates still needs eyes on it before it ships, because authorization is security and you should never trust AI with security decisions you haven't reviewed. Use the skill to accelerate the draft, then review like you'd review any other PR.
The review should focus on the deny paths first. The skill is explicit about the assumptions it made along the way, and those assumptions are where most policy mistakes hide. OWASP's broken access control guidance is a good external reference for what reviewers should look for.
How validation works in Pi
The skill validates the bundle against the real Cerbos compiler.
docker run --rm -v "$(pwd):/policies" ghcr.io/cerbos/cerbos:latest compile /policies
When the compile fails, the skill walks errors in priority order. YAML syntax first, then schema validation, then compile errors, then test failures. One fix per iteration. Tests are never deleted to force a passing state. After three failed attempts the skill stops and hands control back to the developer.
When the bundle is green, the skill writes a summary of what it produced and the assumptions it made. Pi preserves that summary in the conversation alongside the file changes, which keeps the trail readable for the reviewer.
What Pi adds
Two things stand out.
The skill-first design is the headline. Pi treats skills as the way you extend the agent. There's no separate plugin system competing for attention, no proprietary tool format to learn, no need to translate between mental models. The Cerbos policy skill behaves identically to any other Pi skill, which means the muscle memory you build with one carries over to all of them.
Model independence is the second. Pi works with multiple LLM providers through @earendil-works/pi-ai. For teams that need to run authorization work against a specific model, route everything through an internal gateway, or split traffic between providers based on cost or compliance, the skill stays the same. The clarifying questions, the bundle structure, and the validation step are all in the skill, not the model.
For teams already using Pi for application code, adding the Cerbos skill is a single command. Same agent, same conversation, same review process. What changes is the speed at which a policy bundle moves from "we should write that" to a green compile in the repo.
When to slow down
A few scenarios deserve more care than a single conversation can provide.
Anything that touches money, health data, or regulated information should pair the generated policy with a focused review on the deny paths. The skill writes deny tests by default. The review should confirm those tests match the real constraint.
Multi-tenant systems with cross-tenant escalation usually want a PBAC layer on top of the resource policies. The skill writes this when asked. The tenant boundary is a decision the team needs to make first.
If your repo already has policy structure and conventions, point Pi at the existing tree before generating new policies. The skill respects existing structure rather than producing a parallel set of files. Our authorization failure patterns write-up covers what tends to go wrong when teams skip review.
Getting started
Install the skill, open Pi against your policy repo, and describe the next permission you need. The full skill source and the patterns it uses are in our skills repo. For broader context on the workflow, our policy authoring guide covers the same ground from a non-agent angle.
Try Cerbos to deploy and manage the policies the skill produces, or book a workshop to walk through your authorization model with us.
Go deeper:
-
How to adopt externalized authorization (eBook) for the architecture the bundle plugs into
-
Building a scalable authorization system (eBook) for a fuller view of the same problem
Using a different agent?
The Cerbos policy skill also works in:
- Claude Desktop
- Claude Code
- Cursor
- VSCode
- Codex
- OpenCode
- Kiro
FAQ
Tagged in
