> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File System Skill

> Read, write, list, and search files and directories on the local filesystem with configurable permissions and security boundaries.

<CardGroup cols={2}>
  <Card title="Type" icon="tag">
    `file_system`
  </Card>

  <Card title="Variants" icon="code-branch">
    Read Only, Full Access, Sandboxed
  </Card>
</CardGroup>

**Purpose:** The File System skill provides agents with controlled access to the local filesystem, enabling them to read, write, list, and search files and directories.

***

## Common Use Cases

<CardGroup cols={2}>
  <Card icon="file-lines">
    **Reading configuration files**

    Access application configs, environment files, and settings
  </Card>

  <Card icon="file-pen">
    **Creating and managing log files**

    Write logs, audit trails, and operational data
  </Card>

  <Card icon="magnifying-glass">
    **Searching for specific files or content**

    Locate files by name patterns or search content within files
  </Card>

  <Card icon="eye">
    **Monitoring file changes**

    Track modifications, detect configuration drift
  </Card>
</CardGroup>

***

## Variants Overview

| Variant            | Security    | Key Permissions                | Best For                      | Create Command          |
| ------------------ | ----------- | ------------------------------ | ----------------------------- | ----------------------- |
| **Read Only** 🟢   | Safe        | Read, list, search only        | Log monitoring, audits        | `--variant read_only`   |
| **Full Access** 🟡 | Recommended | Read, write, create, delete    | General file operations       | `--variant full_access` |
| **Sandboxed** 🔵   | Secure      | Isolated to specific directory | Testing, untrusted operations | `--variant sandboxed`   |

<Tip>
  **Choosing a variant:** Start with Read Only, upgrade only as needed following the principle of least privilege. See [Variant Configuration](/core-concepts/skills/variant-configuration) for detailed differences.
</Tip>

***

## Configuration

**Example Configuration:**

```json theme={null}
{
  "enable_read_file": true,
  "enable_save_file": false,
  "base_dir": "/var/log",
  "allowed_extensions": ["log"]
}
```

<AccordionGroup>
  <Accordion title="📋 Full Configuration Reference" icon="gear">
    | Parameter             | Type    | Default          | Description                |
    | --------------------- | ------- | ---------------- | -------------------------- |
    | `enable_read_file`    | boolean | true             | Allow file reading         |
    | `enable_save_file`    | boolean | variant-specific | Allow file writing         |
    | `enable_list_files`   | boolean | true             | Allow directory listings   |
    | `enable_search_files` | boolean | true             | Allow content search       |
    | `base_dir`            | string  | "/"              | Root directory restriction |
    | `allowed_extensions`  | array   | \[]              | Whitelist file types       |
    | `max_file_size`       | string  | "10MB"           | Maximum file size          |
    | `follow_symlinks`     | boolean | false            | Follow symbolic links      |
  </Accordion>

  <Accordion title="⚙️ Variant-Specific Defaults" icon="code-branch">
    **Read Only:**

    * `enable_save_file: false` (locked)
    * `enable_delete: false` (locked)

    **Full Access:**

    * All operations enabled

    **Sandboxed:**

    * `base_dir: "/sandbox"` (locked)
    * Full access within sandbox only

    **See:** [Variant Configuration Guide](/core-concepts/skills/variant-configuration)
  </Accordion>
</AccordionGroup>

***

## Quick Start

```bash theme={null}
# Create skill with variant
kubiya skill create --name "Log Reader" --type file_system --variant read_only --enabled

# Associate with agent
kubiya skill associate agent <agent-id> <skill-id>
```

<Card title="View Complete Examples" icon="lightbulb" href="/core-concepts/skills/examples#production-log-analyzer">
  See full production deployment patterns, multi-step workflows, and troubleshooting guides
</Card>

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use base_dir to restrict access" icon="folder-tree">
    Always specify a `base_dir` to limit file operations to a specific directory tree.

    ```json theme={null}
    base_dir: "/opt/myapp"  # Agent can only access files under /opt/myapp
    ```
  </Accordion>

  <Accordion title="Whitelist file extensions" icon="filter">
    Use `allowed_extensions` to restrict which file types the agent can interact with.

    ```json theme={null}
    allowed_extensions: ["yaml", "json", "log"]
    ```
  </Accordion>

  <Accordion title="Start with Read Only" icon="shield-check">
    Begin with the most restrictive variant and only upgrade when write operations are necessary.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting & Related Skills

<AccordionGroup>
  <Accordion title="Permission Denied Errors" icon="triangle-exclamation">
    **Solutions:**

    * Verify `base_dir` includes the target files
    * Check file extensions are in `allowed_extensions`
    * Confirm worker process has OS-level read permissions
  </Accordion>

  <Accordion title="Cannot Write Files" icon="file-slash">
    **Solutions:**

    * Ensure variant is not Read Only
    * Verify `enable_save_file: true` in configuration
    * Check OS-level write permissions on target directory
  </Accordion>

  <Accordion title="Files Outside base_dir Not Accessible" icon="folder-xmark">
    **This is expected behavior for security.** Either adjust `base_dir` to include needed paths or create multiple File System skills with different `base_dir` values.
  </Accordion>
</AccordionGroup>

### Related Skills

<CardGroup cols={2}>
  <Card title="Shell Skill" icon="terminal" href="/core-concepts/skills/shell">
    Execute commands to manipulate files
  </Card>

  <Card title="Python Skill" icon="python" href="/core-concepts/skills/python">
    Process files with Python scripts
  </Card>

  <Card title="File Generation" icon="file-code" href="/core-concepts/skills/file-generation">
    Create formatted files (PDF, CSV, JSON)
  </Card>

  <Card title="View All Skills" icon="layer-group" href="/core-concepts/skills/built-in-skills">
    Return to built-in skills overview
  </Card>
</CardGroup>