# How the .claws Skill File Format Defines Agent Permissions and Tool Access

> Learn how the .claws skill file format defines agent permissions and tool access using YAML manifests and access control lists. Understand resource mapping and runtime enforcement for secure agent operations.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: how-to-guide
- Published: 2026-02-25

---

**The .claws format declares agent capabilities through a YAML-based MANIFEST section containing a permissions array that maps resources like filesystem paths, shell commands, and network endpoints to explicit allow and deny lists, while the ClosedClaw runtime enforces these boundaries by statically validating imported tools against declared capabilities.**

The `asafelobotomy/closedclaw` repository implements a declarative skill system where `.claws` files govern agent behavior through strict capability declarations. The `.claws` skill file format establishes a security model that explicitly defines resource access patterns, allowing developers to create agents that operate within tightly controlled sandboxes validated at both static analysis and runtime phases.

## The .claws File Structure

The `.claws` format organizes skill definitions as YAML-structured sections separated by document delimiters (`---`). Each file begins with a **MANIFEST** section that declares the agent's identity, runtime version, and capability requirements.

The runtime identifier (`closedclaw_agent_v1`) specified in the manifest determines how the engine interprets permission grants. This section establishes the foundation for the agent's security envelope before any tool imports or execution logic is defined.

## Declaring Agent Permissions in the MANIFEST

Within the MANIFEST section, the **`permissions`** key contains an array of capability objects that enumerate exactly what system resources the agent may exercise. Each capability entry specifies a resource type alongside **`allow`** and optional **`deny`** arrays that define the access boundary.

The format supports granular control through these core capability types:

- **`fs.read`** and **`fs.write`** – Govern filesystem access with path-specific allow/deny lists (e.g., `allow: ["~", "/tmp"]`, `deny: ["/etc"]`)
- **`exec`** – Controls shell command execution (e.g., `allow: ["*"]` permits any command)
- **`net.http`** – Manages outbound HTTP/HTTPS requests to specific domains or wildcards
- **`env.read`** – Restricts environment variable access to specific keys (e.g., `keys: ["BRAVE_API_KEY"]`) with optional PII scanning
- **`memory.*`** – Regulates interaction with the internal memory store for persistent state
- **`clipboard`** – Limits clipboard read/write operations (e.g., `allow: ["read", "write"]`)

The **wildcard `*`** grants unrestricted access for a specific capability, while explicit paths and commands enable fine-grained restrictions. By combining `allow` and `deny` directives, skills can expose minimal attack surfaces—such as permitting `fs.write` only in the user’s home directory while explicitly blocking system paths like `/etc` or `/boot`.

## How the Runtime Enforces Tool Access

The ClosedClaw engine validates tool imports through static analysis before execution begins. When a skill imports utilities from `@closedclaw/tools`, the analyzer cross-references each function against the **declared capabilities** in the MANIFEST.

For example, in `src/agents/clawtalk/skills/system.claws`, the TypeScript engine imports `readFile`, `writeFile`, `runCommand`, and `clipboard`. The static analyzer verifies that these imports are covered by corresponding capability declarations:

```typescript
import { readFile, writeFile, listDir, runCommand, clipboard } from "@closedclaw/tools";

export async function execute(args: SystemArgs) {
  if (args.command) return runCommand(args.command);      // Requires exec capability
  if (args.content && args.path) return writeFile(args.path, args.content); // Requires fs.write
  if (args.path) return readFile(args.path);               // Requires fs.read
  if (args.clipboardOp === "read") return clipboard.read(); // Requires clipboard
  if (args.clipboardOp === "write" && args.content) return clipboard.write(args.content);
  return listDir(args.path ?? ".");
}

```

If an imported tool lacks a corresponding capability declaration in the MANIFEST, the static analyzer flags the violation and prevents the skill from loading, ensuring that agents cannot bypass permission boundaries through hidden imports.

## Permission Patterns from Real Skills

The `src/agents/clawtalk/skills/` directory contains production examples demonstrating different permission profiles. The **system skill** (`system.claws`) requires broad system access for maintenance tasks:

```yaml
---
id: "system"
version: "1.0.0"
schema_version: "3.0"
runtime: "closedclaw_agent_v1"
memory_strategy: "ephemeral"
permissions:
    - capability: "fs.read"
      allow: ["~", "/tmp", "/etc"]
    - capability: "fs.write"
      allow: ["~", "/tmp"]
      deny: ["/etc", "/boot", "/root", "/system"]
    - capability: "exec"
      allow: ["*"]
    - capability: "clipboard"
      allow: ["read", "write"]
---

```

Conversely, the **research skill** (`research.claws`) focuses on network and external API access while maintaining strict filesystem isolation:

```yaml
---
permissions:
    - capability: "net.http"
      allow: ["*"]
    - capability: "fs.read"
      allow: ["/tmp", "~/.closedclaw/cache"]
    - capability: "env.read"
      keys: ["BRAVE_API_KEY", "PERPLEXITY_API_KEY"]
      pii_scan: true
---

```

Additional reference files include `code.claws`, which implements restricted filesystem access for code generation tasks, and `memory.claws`, which exclusively governs persistent memory read/write operations.

## Summary

- The `.claws` format uses YAML document sections separated by `---`, with permissions declared in the MANIFEST section
- Capabilities utilize **allow** and **deny** arrays with wildcard `*` support to create granular access controls for filesystem, execution, network, and environment resources
- The `closedclaw_agent_v1` runtime validates all `@closedclaw/tools` imports against declared capabilities through static analysis, rejecting unauthorized tool usage before execution
- Production skills in `src/agents/clawtalk/skills/` demonstrate practical permission patterns ranging from unrestricted system access to isolated network-only configurations

## Frequently Asked Questions

### What happens if a .claws skill imports a tool without declaring the corresponding capability?

The ClosedClaw static analyzer performs a validation check during skill loading. If an imported function from `@closedclaw/tools` lacks a matching capability declaration in the MANIFEST permissions array, the analyzer flags the discrepancy and prevents the skill from initializing, ensuring that tool access is strictly bounded by explicit permission grants.

### Can .claws permissions use wildcards for broad access control?

Yes. The permissions system supports the wildcard character `*` within allow arrays to grant unrestricted access to a capability category. For example, `allow: ["*"]` in an `exec` capability permits any shell command, while `allow: ["*"]` in `net.http` enables outbound requests to any domain. However, best practices recommend explicit path and command restrictions to minimize security exposure.

### How does the MANIFEST section structure permission declarations?

The MANIFEST section contains a top-level **`permissions`** key that holds an array of capability objects. Each object declares a specific **`capability`** identifier (such as `fs.read` or `exec`) followed by **`allow`** arrays listing permitted resources and optional **`deny`** arrays blocking specific paths or operations. This structure enables fine-grained security policies that mix broad access with explicit restrictions.

### Where are example permission definitions located in the ClosedClaw repository?

Reference implementations reside in `src/agents/clawtalk/skills/`, including `system.claws` for filesystem and execution permissions, `research.claws` for network and environment variable access, `code.claws` for restricted code generation contexts, and `memory.claws` for persistent storage operations. These files demonstrate production-ready permission configurations for the `asafelobotomy/closedclaw` agent system.