Menu · Writing rules

Writing rules

A rule is one markdown file. The frontmatter is the rule and the text under it says why.

Save rules under .paws/ in a repo to share them with the team, or under ~/.paws/ for every project you work on. A rule applies from the next tool call, with nothing to reload. You can also ask Claude to write one, as in "load humanizer before I open a PR, via paws". See The paws skill.

The rule file

.paws/pre-tool/humanizer-pr.md
---name: humanizer-pr     # unique; shown in denies and the audit logevent: pre-tool        # when it can firematcher:               # every field you set must match  tool: Bash  command_regex: (^|[;&|\n])\s*gh\s+pr\s+(create|edit)\baction:                # the skill to load first  type: require-skill  skill: humanizer---PR titles and bodies read like a person wrote them.
KeyRequiredMeaning
nameyesUnique. Lowercase letters, digits and dashes. Shown in deny messages and the audit log.
eventyesWhen the rule can fire. See Events.
matchernoWhich calls it covers. Every field you set must match. Leave it out to cover every call of the event.
whennoOne condition, or a list where all must hold.
action.typeyesrequire-skill, the only action.
action.skillyesThe skill's name, exactly as name: in its SKILL.md.
action.deny_messagenoReplaces the default deny text.
action.messagenosession-start only. Replaces the default context text.
action.on_missnoload-required, the default, or digest. See Digests.
action.digestwith digestPath to the digest file, relative to the rule's folder.

paws ignores keys it doesn't know, so a newer rule file still loads on an older paws. It also ignores a typo like comand_regex, and the rule then matches more than you meant. explain flags unknown keys on a ! line.

Events

eventFires oncommand_regex sees
pre-toolany tool callthe tool's target, in the next table
pre-commita Bash call that runs git commit or git commit-treethe command
pre-pusha Bash call that runs git pushthe command
session-starta session startingstartup, resume, clear or compact

pre-commit and pre-push need no command_regex. They match a real git commit or git push, chained or written as git -C dir commit. git commit-tree makes a commit too, so it counts. git commit-graph doesn't. session-start can't deny anything. It adds a note to Claude's context naming the skill.

For pre-tool, the target depends on the tool:

ToolTarget
Bashcommand
Read, Write, Editfile_path
NotebookEditnotebook_path
Grep, Globpattern
WebFetchurl
WebSearchquery
Task, Agentprompt
mcp__*the whole tool input as JSON

Matchers

FieldMatches
toolA tool name, an A|B list, or a prefix such as mcp__slack__*. Leave it out for any tool.
command_regexA Go RE2 regular expression over the target.
file_glob**, *, ? and {a,b} over the file path, for Read, Write, Edit and NotebookEdit. A relative glob matches at any depth, so *.py is every Python file.
mcp_actionsend, create, update, delete, or an A|B list. MCP tools only.

file_glob also matches Read. To gate changes only, add tool: Write|Edit.

Regex tips

command_regex is Go RE2, which has no lookahead, lookbehind or backreferences. Anchor a Bash pattern at a command boundary so chained commands match and quoted text doesn't:

(^|[;&|\n])\s*git\s+push\b
  • This matches git push at the start, after &&, ; or |, or on a new line. It doesn't match echo "git push".
  • Add (sudo\s+)? or (\w+=\S*\s+)* for prefixed forms.
  • Cover every spelling of a flag. rm -rf is also -fr, -Rf, -r -f and --recursive --force.
  • End a word with (\s|$) rather than \b, since publish\b also matches npm run publish-docs. With no lookahead, list the forms you want. --force(\s|$) spares --force-with-lease.
  • Write regexes and globs bare in YAML, or in single quotes when they start with *, {, & or ! or contain : . Double quotes turn \s and \b into YAML escapes and break the rule.

MCP actions

paws sorts an MCP tool by the first verb in its name, whatever the server. slack_send_message is a send, create_pull_request a create, list_messages a read. Reads never match. Creating a comment, draft, message or reply counts as a send, and so does updating a draft. So one rule covers every Slack tool that sends:

matcher:  tool: mcp__slack__*  mcp_action: send      # send, create, update or delete

when conditions

ConditionHolds when
dependency:PKGThe repo root lists PKG as a dependency in package.json, go.mod, Cargo.toml, pyproject.toml or requirements.txt.
repo-marker:PATHPATH exists under the repo root.
new-fileThe Read, Write or Edit target doesn't exist yet.
no-edit-matching:GLOBNo successful Edit or Write of a matching path in the last 1 MB of the transcript. Denied or failed edits don't count.
agent-count>NClaude spawned more than N subagents since your last prompt.

The repo root is the nearest folder above Claude's working directory with a .git. Here is a shortened version of the testing pack's rule. It loads a TDD skill before source changes while no test has been touched:

matcher:  tool: Write|Edit  file_glob: 'src/**/*.{ts,tsx,go,py}'when: 'no-edit-matching:{*.test.*,*_test.*,tests/**}'

The action

require-skill is the only action. It denies the call until skill was loaded in the last 20 agent turns, then allows it. paws skips a rule with any other action, or an event not listed above. Claude Code shows a one-line notice and explain lists it as ! skipped. The default deny reads:

This action requires the "humanizer" skill. Invoke it with the Skill tool, then retry this exact command.

Digests

For a skill people may not have installed, ship a short digest of its rules next to the rule file. The deny then carries the digest text. Once that deny is in the 20-turn window, the retry passes without the skill installed. A loaded skill still passes first.

action:  type: require-skill  skill: aws-s3  on_miss: digest               # default: load-required  digest: digests/aws-s3.md     # relative to the rule's folder, at most 7,000 bytes

The path must stay inside the rule's folder, so no ... A missing or oversized digest falls back to the plain deny, and the audit record notes the error. paws tracks delivery by rule name, so two rules with the same name share it.

Where rules load from

  • Every .paws/ folder from Claude's working directory up to the repo root. Outside a repo, up to your home folder if you're under it. Anywhere else, only the working directory's own .paws/.
  • Your user folder, ~/.paws/ or $PAWS_HOME, in every project. Packs go in ~/.paws/packs/ and portal settings in ~/.paws/portal/, so they load from here too.
  • Any .md file at any depth, except README.md, SKILL.md, and anything under a skills/ or digests/ folder. A symlinked .paws folder works.

There's no precedence. Every matching rule applies, wherever it came from, and one deny names every missing skill.