system-boundaries

A guide to keeping an AI coding assistant's internal code separate from outside systems such as language-model services, plug-in servers, files, shell commands, Git, and login services.

In plain words
What is it for?
Use it when adding an integration or deciding where code for files, shell commands, Git, APIs, or plug-in servers should live.
Why use it?
It prevents outside-system errors and security checks from being handled differently throughout the code. Central boundaries make failures, retries, permissions, and unexpected responses easier to manage.

Skill for Claude CodeCodex

Part of the claude-code-superpowers plugin — 16 skills shipped together

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/techymt/claude-code-superpowers/system-boundaries
Any agent
npx skills add TechyMT/claude-code-superpowers --skill system-boundaries
Clone the repo
git clone --depth 1 https://github.com/TechyMT/claude-code-superpowers

Made for: Claude Code, Codex.

Or install claude-code-superpowers, the plugin that ships this one along with the rest of its 16 skills.

Per session 82 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,783 The whole file, excluding the scripts and references it only reads on demand.
Security scan C 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00082 $0.01783
Opus 5 $0.00041 $0.00892
Sonnet 5 $0.00016 $0.00357
Haiku 4.5 $0.00008 $0.00178

Measured 3d ago against content hash 896fc195c5b8, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade C, and why

system-boundaries scanned grade C with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Reaches for credential fileshighPrivilege escalation

SSH keys, cloud credentials, git-credentials, .npmrc, /etc/shadow: reading these is how a config file becomes a credential leak.

The key security detail: Claude Code uses `execFile()` (argument arrays) everywhere, never `exec()` (shell strings). This applies to git, bash helpers, and any other subprocess. A tool input of `"$(cat ~/.ssh/id_rsa)"` w
skills/system-boundaries/SKILL.md · 139 lines

How it starts

The opening of the file, as written. The whole thing — 139 lines — stays where its author put it; the contents beside it link to each section on GitHub.

System Boundaries

The pattern

Claude Code has a clear inside/outside line. Inside: the conversation loop, tool execution, state management, permission checking, and UI rendering. Outside: the Claude API (LLM inference), MCP servers (dynamic tool extension), the local file system, the shell, Git, OAuth providers, and remote CCR infrastructure.

The boundary is managed by: the services/api/ module for the Claude API, the services/mcp/ module for MCP clients, sandboxed path resolution for file system access, and execFile wrappers (never exec with shell interpolation) for shell and Git commands.

Why this matters

Each external system has its own failure modes. The Claude API can return 429 (rate limit), timeout, or return malformed tool call JSON. MCP servers can disconnect or return unexpected schemas. The file system can have permission errors or ENOENT. Shell commands can hang or have non-zero exit codes. Git can be absent or on an unexpected version.

By routing all external access through boundary modules (services/api/, services/mcp/, utils/git.ts), error handling and retry logic lives in one place. Tools don't need to handle rate limits or reconnection — they call the boundary, and the boundary handles the failure modes of that external system.

How to apply it

  1. Claude API: don't call the Anthropic API directly from a tool. Use the services in services/api/. This gives you automatic retry, token budget tracking, and streaming.
  2. MCP: don't implement a custom MCP client. Use services/mcp/MCPServerConnection. Register tools via mcpClients in ToolUseContext.options.
  3. File system: always resolve paths through getResolvedPath() or equivalent — this enforces the sandbox (additional working directories) and prevents path traversal. Use fs.promises (not sync variants).
  4. Shell commands: use execFileNoThrow() or execFileSafe() from utils/bash/ — these pass arguments as arrays (not strings), preventing shell injection. Never use exec() with string interpolation.
  5. Git: use getGitStatus(), getBranch(), getDefaultBranch() from utils/git.ts — these wrap git in execFileNoThrow and handle the "not a git repo" case gracefully.
  6. New external service: create a services/[name]/ module, implement error handling for that system's failure modes, and expose a clean interface that tools can call without knowing about HTTP status codes or connection state.

Read the full file on GitHub · 139 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 3d ago First seen · 139 lines · 82 tokens per session scan C 896fc195c5b8

Subscribe to this mod's changes

system-boundaries is a skill published in the GitHub repository TechyMT/claude-code-superpowers (5 stars, last pushed 5mo ago), licensed MIT. It adds 82 tokens to every session and 1,783 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it C with 1 finding (reaches for credential files). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.

obra/superpowers · 21 tokens

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

obra/superpowers · 37 tokens

auto-perf-optimize

Run agent-driven VS Code performance or memory investigations. Use when asked to launch Code OSS, automate a VS Code scenario, run the Chat memory smoke runner, capture renderer heap snapshots, take workflow screenshots, compare run summaries, or drive a repeatable scenario before heap-snapshot analysis.

microsoft/vscode · 62 tokens

chat-perf

Run chat perf benchmarks and memory leak checks against the local dev build or any published VS Code version. Use when investigating chat rendering regressions, validating perf-sensitive changes to chat UI, or checking for memory leaks in the chat response pipeline.

microsoft/vscode · 51 tokens

chat-pet-sprite-creation

Use when creating or changing VS Code chat pet sprite art, sprite sheets, state animations, eye treatments, Stable/Insiders variants, or pet transitions under src/vs/workbench/contrib/chat/browser/widget/media/chatPet.

microsoft/vscode · 53 tokens

cpu-profile-analysis

Analyze V8/Chrome CPU profiles (.cpuprofile) and DevTools trace files (Trace-.json). Use when: profiling performance, investigating slow functions, comparing code paths, finding bottlenecks, analyzing timeToRequest, understanding call trees from sampling profiler data, analyzing layout/paint/rendering, investigating…

microsoft/vscode · 71 tokens