Claude Code's Permission Model for Skill Builders

Every skill builder has hit the same wall. You build something powerful, you test it, it works -- and then real users abandon it after two sessions because it keeps interrupting them with permission prompts. The skill is not broken. It is fighting the security model instead of working with it.

Understanding Claude Code's permission architecture is not optional for skill builders. It is the difference between a skill that feels seamless and one that feels like navigating airport security every time you use it.

A Note on Sources

The permission model details discussed here are drawn from CCLeaks community analysis of publicly available Claude Code artifacts. This content is AI-generated, may contain errors, and is not affiliated with or endorsed by Anthropic. Treat these findings as informed signal reading rather than official documentation. The architectural patterns described are consistent with observable behavior, but specific implementation details may differ from what ships in production.

Key Takeaways

• Claude Code uses a 3-layer permission cascade: Tool Registry Filter, Per-Call Permission Check, and Interactive User Prompt
• Six permission modes exist: Default (Interactive), Plan Mode, Bypass Permissions, Don't Ask, Accept Edits, and Auto (ML Classifier)
• The YOLO classifier (classifyYoloAction()) uses Claude itself to evaluate whether a tool call is safe enough to auto-approve
• Skills that trigger HIGH risk classifications on every invocation train users to blindly approve or uninstall -- neither outcome is desirable
• The read-first architecture pattern (read, analyze, plan, then batch writes) minimizes permission prompts to at most one per invocation

The Three-Layer Permission Model

Claude Code's security architecture operates as a cascade. Every tool invocation passes through three layers before it executes. Understanding this cascade is the key to building skills that do not trigger unnecessary friction.

Layer 1: Tool Registry Filter

The first layer is a static filter. Before any tool call reaches the model or the user, the Tool Registry checks whether the tool is even available in the current session. This layer handles broad capability gating -- whether file system access is enabled, whether network calls are permitted, whether bash execution is allowed.

For skill builders, this layer is mostly invisible. If your skill uses standard tools (Read, Write, Edit, Bash, Grep) -- the same 43 built-in tools that ship with Claude Code -- they are registered by default. But if your skill depends on MCP tools or custom integrations, you need to ensure those tools are registered in the user's environment. A skill that fails at Layer 1 produces confusing errors because the tool simply does not exist from the model's perspective.

Practical implication: Document your skill's tool dependencies clearly. If your skill requires an MCP server, say so upfront. Users who hit Layer 1 failures will not debug them -- they will uninstall your skill.

Layer 2: Per-Call Permission Check

This is where most skill builders get tripped up. Every individual tool call is evaluated against the current permission mode and the tool's risk classification. This layer decides whether the call proceeds silently, requires user approval, or gets blocked entirely.

The system classifies tool calls along two dimensions:

Tool safety flags:

• isReadOnly -- operations that only read data (file reads, searches, directory listings)
• isDestructive -- operations that modify state irreversibly (file writes, git operations, network requests)

Risk levels:

• LOW -- read-only operations, safe searches, non-destructive inspections
• MEDIUM -- file modifications, non-destructive writes, reversible state changes
• HIGH -- destructive bash commands, force operations, system modifications

A skill that triggers a HIGH risk classification on every invocation will train users to either blindly approve everything (defeating the purpose of security) or stop using the skill entirely. Neither outcome is what you want.

Layer 3: Interactive User Prompt

When Layer 2 determines that user approval is needed, Layer 3 presents the approval dialog. This is the permission prompt that users see -- the one that interrupts their workflow and forces a decision.

The prompt includes context about what the tool wants to do, which files it will affect, and what command it plans to execute. The user can approve, deny, or approve for the remainder of the session.

The critical insight: Layer 3 is where user trust is built or destroyed. A skill that hits Layer 3 once per session for a reasonable operation builds trust. A skill that hits Layer 3 twelve times in a single invocation destroys it.

The Six Permission Modes

Claude Code supports six permission modes that change how the Layer 2 check behaves. Understanding these modes helps you design skills that work well across different user configurations.

Default (Interactive)

The standard mode. Read operations pass silently. Write operations require approval. Destructive operations always require approval. This is what most users run, and it is the mode you should optimize for.

Plan Mode

An explicit planning-first mode where the system presents its intended actions before executing any of them. Users approve the plan as a whole rather than individual operations. Skills that generate multi-step execution plans work naturally with this mode.

Bypass Permissions

Exactly what it sounds like. All permission checks are skipped. Power users and CI/CD pipelines use this mode. Your skill should never assume this mode is active -- always design for the interactive case.

Don't Ask

Similar to bypass but with logging. Operations proceed without prompts but are recorded for audit. Enterprise deployments commonly use this mode.

Accept Edits

A middle ground where file edits are auto-approved but destructive bash commands still require approval. This mode is popular with developers who trust their skills to make correct edits but want a safety net for system operations.

Auto (ML Classifier)

The most sophisticated mode. A function called classifyYoloAction() uses Claude itself to evaluate whether a specific tool call is safe enough to proceed without user approval. This is effectively an AI-powered security layer that learns what "normal" looks like for a given workflow.

For skill builders, the Auto mode is both an opportunity and a challenge. If your skill's operations are predictable and clearly benign, the classifier will learn to approve them automatically. If your operations are ambiguous or vary significantly between invocations, the classifier may inconsistently gate them, creating an unpredictable user experience.

Bash AST-Level Analysis

One of the more technically impressive security features is the Bash AST-level analysis that runs before any shell command executes. The system parses the bash command into an abstract syntax tree and inspects it for dangerous patterns before it reaches the shell.

This means the security model does not just look at the command string -- it understands command structure. A command like rm -rf / is caught not by string matching but by structural analysis of the command tree.

What this means for skills: If your skill generates bash commands, keep them simple and direct. Complex piped commands, nested subshells, and dynamically constructed command strings are harder for the AST analyzer to classify, which means they are more likely to trigger permission prompts or outright blocks.

Specific patterns the analyzer watches for:

• Sleep protection: sleep N where N is 2 seconds or greater is flagged. If your skill needs to wait for an external process, use polling with short intervals rather than long sleeps.
• Destructive patterns: Force flags (-f, --force), recursive deletion, and root-level operations are flagged regardless of context.
• Network operations: Outbound connections are evaluated against allowed host lists.

Prompt Injection Defenses

The permission model also protects against prompt injection -- attempts by malicious content to hijack the model's behavior through crafted inputs.

Unicode Sanitization

Input text is sanitized for Unicode control characters that could alter how the model interprets instructions. This includes bidirectional text markers, zero-width characters, and other invisible Unicode sequences that could be used to hide malicious instructions.

Subprocess Isolation

Tool calls execute in isolated subprocess environments. A compromised tool call cannot access the state of other tool calls or modify the model's context directly.

Tool Result Budgeting

The system limits how much data a tool can return to the model. This prevents an attacker from using a tool call to inject a large volume of manipulative text into the context window.

Deep Link Validation

ASCII control characters are rejected in URLs and file paths. Length limits prevent buffer-overflow-style attacks through excessively long inputs.

For skill builders: These defenses protect your users, but they also constrain your skill's behavior. If your skill processes external content (web pages, user documents, API responses), be aware that the content is sanitized before it reaches the model. This is especially relevant for skills that manage context across long sessions. Design your skill to work with sanitized content rather than relying on exact character preservation.

Hook Trust Requirements

If your skill uses hooks -- pre-tool or post-tool callbacks that execute custom logic -- every hook requires workspace dialog approval. This means the first time a user runs your skill with hooks, they will see an approval prompt for each hook.

This is a deliberate friction point. Hooks execute arbitrary code in the user's environment, and the security model treats them accordingly. You cannot bypass this requirement.

Design guidance: Minimize the number of hooks your skill requires. Each hook is an approval prompt on first use. A skill with one well-designed hook that covers multiple scenarios is better than a skill with five hooks covering individual cases.

Designing Skills That Flow Through the Permission Model

With the security architecture understood, here are concrete patterns for building skills that work with the permission model instead of against it.

Pattern 1: Read-First Architecture

Structure your skill to do all its reading and analysis before any writing. Read operations flow through the permission model silently in all modes. By front-loading reads, your skill builds context without triggering any prompts, and users see the skill "thinking" before it asks to act.

Step 1: Read files, search codebase, gather context (no prompts)
Step 2: Analyze and plan (no prompts)
Step 3: Present plan to user (no prompts)
Step 4: Execute writes in a batch (one approval if needed)

This pattern means your skill triggers at most one permission prompt per invocation rather than one per file it needs to modify.

Pattern 2: Predictable Operations

The Auto mode classifier learns from patterns. If your skill always writes to the same types of files (test files, documentation, configuration), the classifier learns that these operations are safe for your skill. If your skill writes to unpredictable locations, the classifier cannot build a reliable safety model.

Design your skill to be boring and predictable in its operations even if its outputs are creative and varied.

Pattern 3: Minimal Bash, Maximum API

Every bash command goes through AST analysis. Every file operation through the Edit tool gets simpler classification. Prefer Edit over sed. Prefer Read over cat. Prefer Grep over grep. The built-in tools have well-understood risk profiles. Custom bash commands do not.

Pattern 4: Explicit Destructive Intent

When your skill must perform a destructive operation, make the intent explicit in the skill's output. Tell the user what is about to happen and why before the permission prompt appears. A user who understands why they are seeing a prompt approves it quickly. A user who sees an unexpected prompt hesitates, and that hesitation erodes trust.

Pattern 5: Graceful Denial Handling

Users will sometimes deny permission prompts. Your skill must handle denial gracefully. Do not crash. Do not retry the same operation immediately. Offer an alternative path or explain what the skill cannot do without the denied permission.

Why the Permission Model Makes the Marketplace Possible

Here is the argument that ties everything together: the permission model is not an obstacle to building great skills. It is the foundation that makes a skill marketplace viable. As the CCLeaks analysis has shown, the platform is evolving rapidly, and trust infrastructure is what makes that evolution possible.

Without a robust permission model, installing a skill from an unknown publisher would be reckless. Every skill would have unconstrained access to your codebase, your file system, and your network. No one would install skills from strangers, and the marketplace would not exist.

The permission model makes trust scalable. Users can install skills from publishers they have never heard of because they know the security layers will prevent those skills from doing anything dangerous without explicit approval. As users build trust with a specific skill, they can adjust their permission mode to reduce friction.

This is the same pattern that made mobile app stores work. Sandboxed permissions, explicit user consent, and graduated trust. The skills that succeed in a permission-gated environment are the ones designed to work within it, not around it.

Frequently Asked Questions

What is Claude Code's permission model?

Claude Code uses a 3-layer permission cascade that evaluates every tool invocation before execution. Layer 1 checks if the tool is registered, Layer 2 evaluates the call against the current permission mode and risk classification, and Layer 3 presents an interactive approval dialog when needed.

What are the six permission modes?

The six modes are Default (Interactive), Plan Mode, Bypass Permissions, Don't Ask, Accept Edits, and Auto (ML Classifier). Each mode changes how Layer 2 evaluates tool calls, from requiring approval for every write operation to automatically classifying calls using AI.

How does the YOLO classifier work?

The Auto mode uses a function called classifyYoloAction() that leverages Claude itself to evaluate whether a specific tool call is safe enough to proceed without user approval. It learns what "normal" looks like for a given workflow, so predictable, consistent operations are more likely to be auto-approved.

How do I make my skill pass permission checks cleanly?

Use a read-first architecture: gather all context through read operations (which pass silently), analyze and plan without prompts, then batch write operations into a single approval step. Prefer built-in tools (Edit, Read, Grep) over custom bash commands, and keep bash commands simple and direct.

Why does the permission model matter for skill marketplace adoption?

The permission model is what makes users willing to install skills from unknown publishers. Without it, every skill would have unconstrained access to the user's codebase, file system, and network. The model makes trust scalable -- the same pattern that made mobile app stores viable.

The Bottom Line for Skill Builders

Build your skills as if every user is running in Default (Interactive) mode with full permission prompts enabled. Minimize write operations. Batch them when possible. Use built-in tools over custom bash. Handle permission denials gracefully.

The skills that feel effortless to use are not the ones that avoid the security model. They are the ones that flow through it so cleanly that users forget it is there.

That is the standard to build toward. The permission model is your ally -- it is what makes users willing to try your skill in the first place.

---

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.