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
---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.| Key | Required | Meaning |
|---|---|---|
name | yes | Unique. Lowercase letters, digits and dashes. Shown in deny messages and the audit log. |
event | yes | When the rule can fire. See Events. |
matcher | no | Which calls it covers. Every field you set must match. Leave it out to cover every call of the event. |
when | no | One condition, or a list where all must hold. |
action.type | yes | require-skill, the only action. |
action.skill | yes | The skill's name, exactly as name: in its SKILL.md. |
action.deny_message | no | Replaces the default deny text. |
action.message | no | session-start only. Replaces the default context text. |
action.on_miss | no | load-required, the default, or digest. See Digests. |
action.digest | with digest | Path 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
| event | Fires on | command_regex sees |
|---|---|---|
pre-tool | any tool call | the tool's target, in the next table |
pre-commit | a Bash call that runs git commit or git commit-tree | the command |
pre-push | a Bash call that runs git push | the command |
session-start | a session starting | startup, 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:
| Tool | Target |
|---|---|
| Bash | command |
| Read, Write, Edit | file_path |
| NotebookEdit | notebook_path |
| Grep, Glob | pattern |
| WebFetch | url |
| WebSearch | query |
| Task, Agent | prompt |
mcp__* | the whole tool input as JSON |
Matchers
| Field | Matches |
|---|---|
tool | A tool name, an A|B list, or a prefix such as mcp__slack__*. Leave it out for any tool. |
command_regex | A 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_action | send, 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 pushat the start, after&&,;or|, or on a new line. It doesn't matchecho "git push". - Add
(sudo\s+)?or(\w+=\S*\s+)*for prefixed forms. - Cover every spelling of a flag.
rm -rfis also-fr,-Rf,-r -fand--recursive --force. - End a word with
(\s|$)rather than\b, sincepublish\balso matchesnpm 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\sand\binto 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 deletewhen conditions
| Condition | Holds when |
|---|---|
dependency:PKG | The repo root lists PKG as a dependency in package.json, go.mod, Cargo.toml, pyproject.toml or requirements.txt. |
repo-marker:PATH | PATH exists under the repo root. |
new-file | The Read, Write or Edit target doesn't exist yet. |
no-edit-matching:GLOB | No 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>N | Claude 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 bytesThe 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
.mdfile at any depth, exceptREADME.md,SKILL.md, and anything under askills/ordigests/folder. A symlinked.pawsfolder works.
There's no precedence. Every matching rule applies, wherever it came from, and one deny names every missing skill.