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

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:

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:

---
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:

---
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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}