From 259a7d710b50cc31f3f0ee2d47622c7dafab5f6f Mon Sep 17 00:00:00 2001 From: William Reade Date: Wed, 4 Nov 2026 17:27:09 +0000 Subject: [PATCH] docs: describe the permissions the guardrails skill needs Stacklet access is read-only GraphQL; Claude Code asks to approve the MCP query tool, the bundled scripts and temp files, and users write their own rules; the cache and scope file locations; and nested `claude -p` calls spending the user's tokens. Co-Authored-By: Claude Opus 5.5 --- README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 11313ff..470aa5e 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,20 @@ away from defining infrastructure that violates deployed policies. Requires the Stacklet MCP server and Python 3.11+ (the scripts use only the standard library). -The skill runs its bundled scripts with `python3`, so Claude Code asks you to approve the first -call. (Don't expect the skill to pre-approve this itself: a skill that declares `allowed-tools` -needs an approval just to load, and is silently skipped in headless `claude -p` runs.) +## Permissions -To stop the prompts, add a permission rule for the skill's scripts in your own settings. +- **Stacklet**: the skill only runs GraphQL queries, through the MCP server's + `platform_graphql_query`, and writes nothing to the platform. +- **Claude Code tools**: approve `mcp____platform_graphql_query`, `python3` running the + skill's bundled scripts, and creating and writing files in a temp directory (the sync saves + query results there before ingesting them). The skill doesn't pre-approve anything itself. A + skill that declares `allowed-tools` needs an approval just to load, and headless `claude -p` runs + skip it silently. To stop the prompts, add permission rules to your own settings. The sync runs + as a background sub-agent, which can't answer a prompt: if it is denied a tool, the main session + runs the sync itself and asks you there. +- **Files**: the cache is under `~/.stacklet/guardrail-cache/` (set `STACKLET_GUARDRAILS_CACHE` to + move it). Each repo's scope is recorded in `.stacklet/guardrails/scope.json` at the repo root, + which is meant to be committed. +- **Model calls**: distilling guardrails and assessing the posture run `claude -p` under your own + Claude login, so they spend your tokens. To use another tool instead, see + `plugins/stacklet/skills/guardrails/references/inference.md`.