Policy Engine Builder

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini policy engine:

• INVOKE gemini-cli-docs skill

• QUERY for the specific policy topic

• BASE all responses EXCLUSIVELY on official documentation loaded

Overview

This skill provides guidance for configuring Gemini CLI's Policy Engine using TOML rules. The policy engine controls tool execution with fine-grained allow/deny/ask rules.

When to Use This Skill

Keywords: policy engine, policy toml, tool policy, allow deny, gemini rules, security policy, mcp policy

Use this skill when:

• Restricting which tools Gemini can use

• Creating enterprise security policies

• Controlling MCP server permissions

• Setting up approval workflows

• Auditing tool execution rules

Policy File Locations

User Policies

~/.gemini/policies/ ├── default.toml # User default rules └── security.toml # Additional security rules

Project Policies

.gemini/policies/ ├── project.toml # Project-specific rules └── team.toml # Team conventions

System Policies (Enterprise)

/etc/gemini-cli/policies/ # Linux /Library/Application Support/GeminiCli/policies/ # macOS C:\ProgramData\gemini-cli\policies\ # Windows

Rule Structure

Basic Rule

[[rule]] toolName = "run_shell_command" decision = "ask_user" priority = 100

Rule Fields

Field Type Description

toolName

string/array Tool name(s) to match

mcpName

string MCP server name

argsPattern

string Regex for tool arguments

commandPrefix

string/array Shell command prefix(es)

commandRegex

string Regex for shell commands

decision

string allow , deny , or ask_user

priority

number 0-999 within tier

modes

array Optional: yolo , autoEdit

Decision Types

Allow

Automatically approve without prompting:

[[rule]] toolName = "read_file" decision = "allow" priority = 100

Deny

Block execution entirely:

[[rule]] toolName = "run_shell_command" commandPrefix = "rm -rf" decision = "deny" priority = 999

Ask User

Prompt for confirmation:

[[rule]] toolName = "write_file" decision = "ask_user" priority = 100

Priority System

Three Tiers

Tier Base Source

Default 1 Built-in defaults

User 2 User policies

Admin 3 System/enterprise

Priority Calculation

The formula is: final_priority = tier_base + (toml_priority / 1000)

Example:

• User rule with priority 100 → 2 + (100/1000) = 2.100

• Admin rule with priority 50 → 3 + (50/1000) = 3.050

Higher tier always wins, then higher priority within tier.

Priority Guidelines

Priority Use Case

0-99 Low priority defaults

100-499 Normal rules

500-799 Important restrictions

800-999 Critical security rules

Tool Matching

Single Tool

[[rule]] toolName = "run_shell_command" decision = "ask_user"

Multiple Tools

[[rule]] toolName = ["write_file", "replace"] decision = "ask_user"

All Tools

[[rule]] toolName = "*" decision = "ask_user"

Shell Command Patterns

Command Prefix

Match commands starting with "git"

[[rule]] toolName = "run_shell_command" commandPrefix = "git " decision = "allow" priority = 100

Multiple Prefixes

[[rule]] toolName = "run_shell_command" commandPrefix = ["npm ", "yarn ", "pnpm "] decision = "allow" priority = 100

Command Regex

Match destructive commands

[[rule]] toolName = "run_shell_command" commandRegex = "^(rm|rmdir|del|rd)\s" decision = "deny" priority = 999

Argument Patterns

JSON Argument Matching

Tool arguments are JSON strings:

Deny writes to sensitive paths

[[rule]] toolName = "write_file" argsPattern = ".*\.(env|key|pem|crt)$" decision = "deny" priority = 900

Complex Patterns

Allow reads only from src/

[[rule]] toolName = "read_file" argsPattern = "^\{"path":"src/.*"\}$" decision = "allow" priority = 100

MCP Server Rules

Server-Level Control

Deny all tools from untrusted server

[[rule]] mcpName = "untrusted-server" decision = "deny" priority = 500

Tool-Level Control

Allow specific tool from server

[[rule]] mcpName = "my-server" toolName = "safe_tool" decision = "allow" priority = 100

Wildcards

All tools from server pattern

[[rule]] toolName = "my-server__*" decision = "ask_user" priority = 100

Approval Modes

YOLO Mode Rules

Apply only in YOLO mode (--yolo ):

[[rule]] toolName = "write_file" decision = "allow" modes = ["yolo"] priority = 100

Auto-Edit Mode Rules

Apply in auto-edit mode:

[[rule]] toolName = "replace" decision = "allow" modes = ["autoEdit"] priority = 100

Template Library

Secure Development Environment

Allow read operations

[[rule]] toolName = ["read_file", "glob", "search_file_content", "list_directory"] decision = "allow" priority = 100

Ask for writes

[[rule]] toolName = ["write_file", "replace"] decision = "ask_user" priority = 100

Allow safe git commands

[[rule]] toolName = "run_shell_command" commandPrefix = ["git status", "git diff", "git log", "git branch"] decision = "allow" priority = 200

Ask for other git commands

[[rule]] toolName = "run_shell_command" commandPrefix = "git " decision = "ask_user" priority = 150

Deny destructive commands

[[rule]] toolName = "run_shell_command" commandRegex = "^(rm|rmdir|del|rd|format|mkfs)\s" decision = "deny" priority = 999

Read-Only Mode

Allow all reads

[[rule]] toolName = ["read_file", "glob", "search_file_content", "list_directory", "web_fetch"] decision = "allow" priority = 100

Deny all writes

[[rule]] toolName = ["write_file", "replace", "run_shell_command"] decision = "deny" priority = 500

NPM/Node.js Safe

Allow npm read commands

[[rule]] toolName = "run_shell_command" commandPrefix = ["npm list", "npm outdated", "npm audit"] decision = "allow" priority = 200

Ask for npm install/run

[[rule]] toolName = "run_shell_command" commandPrefix = ["npm install", "npm run", "npm exec"] decision = "ask_user" priority = 150

Deny npm publish

[[rule]] toolName = "run_shell_command" commandPrefix = "npm publish" decision = "deny" priority = 900

MCP Server Restrictions

Deny all external MCP servers by default

[[rule]] toolName = "__" decision = "deny" priority = 100

Allow specific trusted server

[[rule]] mcpName = "trusted-internal-server" decision = "allow" priority = 200

Allow specific tools from another server

[[rule]] toolName = ["other-server__read_docs", "other-server__search"] decision = "allow" priority = 200

Enterprise Lockdown

System-level (Admin tier)

Block all network access

[[rule]] toolName = ["web_fetch", "google_web_search"] decision = "deny" priority = 999

Block all MCP servers

[[rule]] toolName = "__" decision = "deny" priority = 999

Allow only reads

[[rule]] toolName = ["read_file", "glob", "search_file_content"] decision = "allow" priority = 100

Block all shell commands except safe ones

[[rule]] toolName = "run_shell_command" decision = "deny" priority = 500

[[rule]] toolName = "run_shell_command" commandPrefix = ["ls ", "cat ", "echo ", "pwd"] decision = "allow" priority = 600

Validation

Check TOML Syntax

python -c "import tomllib; tomllib.load(open('policy.toml', 'rb'))"

Common Errors

Error Cause Fix

Parse error Invalid TOML Check quotes, brackets

Rule ignored Lower priority Increase priority

Rule conflicts Overlapping patterns Refine patterns

Regex fails Bad escape Use \ for backslash

Debug Rules

Test which rule matches

gemini "Test shell command" --debug-policy

Best Practices

1. Start Restrictive

Default deny, then allow specific

[[rule]] toolName = "*" decision = "ask_user" priority = 1

[[rule]] toolName = "read_file" decision = "allow" priority = 100

2. Use Clear Priorities

Security rules at 900+

[[rule]] commandRegex = "^rm\s" decision = "deny" priority = 999

Normal rules at 100-499

[[rule]] commandPrefix = "git " decision = "allow" priority = 200

3. Document Rules

SECURITY: Block destructive file operations

Reason: Prevent accidental data loss

Author: security-team

Date: 2025-11-30

[[rule]] toolName = "run_shell_command" commandRegex = "^(rm|rmdir)\s+-r" decision = "deny" priority = 999

4. Test Before Deploy

Test in interactive mode first

gemini --policy-file ./test-policy.toml

5. Layer Policies

System policies (enterprise defaults) └── User policies (personal preferences) └── Project policies (project-specific)

Related Skills

• gemini-cli-docs

• Official policy documentation

• toml-command-builder

• Custom command creation

Keyword Registry

Topic Keywords

Basic policy engine , toml rules , tool policy

Decisions allow , deny , ask_user , decision

Matching toolName , commandPrefix , commandRegex , argsPattern

Priority priority tier , rule priority , precedence

MCP mcp policy , mcpName , server rules

Modes yolo mode , autoEdit , approval mode

Test Scenarios

Scenario 1: Create Policy Rule

Query: "How do I create a Gemini policy to block rm commands?" Expected Behavior:

• Skill activates on "policy engine" or "tool policy"

• Provides TOML rule with commandPrefix/commandRegex Success Criteria: User receives working deny rule for destructive commands

Scenario 2: Priority Configuration

Query: "How do Gemini policy priorities work?" Expected Behavior:

• Skill activates on "priority tier" or "rule priority"

• Explains tier system and calculation Success Criteria: User understands tier-based priority (Admin > User > Default)

Scenario 3: MCP Server Policy

Query: "How do I restrict MCP server tools in Gemini?" Expected Behavior:

• Skill activates on "mcp policy" or "server rules"

• Provides mcpName and wildcard patterns Success Criteria: User receives MCP-specific policy rules

Version History

• v1.1.0 (2025-12-01): Added MANDATORY section, Test Scenarios, Version History

• v1.0.0 (2025-11-25): Initial release