File Operations Skill

Direct file system access through Python APIs for efficient reading, searching, and listing operations.

Capabilities

• •Read Files: Read file contents directly without shell overhead or character limits
• •Glob Matching: Fast file pattern matching with glob syntax (.py, **/.txt, etc.)
• •Code Search: Search file contents using regex patterns (grep-like functionality)
• •Metadata: Get file size, modification time, and other attributes

Advantages Over Shell Commands

Quick Start

To use this skill in the Agent, call it with the following format:

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["<command>", "<args>..."]
}

Available commands: read, glob, search, list, summarize

Usage Examples

1. Read File Contents

Read a single file (works with large files):

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["read", "path/to/file.py"]
}

Returns:

{
    "success": true,
    "content": "file contents here...",
    "encoding": "utf-8",
    "size": 1234,
    "lines": 42
}

2. Find Files with Glob Patterns

Find all Python files recursively:

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["glob", "--pattern", "**/*.py"]
}

Returns:

{
    "success": true,
    "files": [
        {"path": "agent/llm.py", "size": 1024, "modified": "2024-01-20"},
        {"path": "agent/orchestor.py", "size": 40960, "modified": "2024-01-21"}
    ],
    "count": 2
}

Common patterns:

• •**/*.py - All Python files recursively
• •*.txt - Text files in current directory
• •scripts/**/*.sh - Shell scripts in scripts directory
• •test_*.py - Test files starting with "test_"

3. Search File Contents (Grep)

Search for patterns in files:

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["search", "--pattern", "class \\w+Agent", "--file-pattern", "*.py"]
}

Returns:

{
    "success": true,
    "matches": [
        {
            "file": "agent/orchestor.py",
            "line": 42,
            "content": "class ConversationContext:",
            "match": "class ConversationContext"
        }
    ],
    "total_matches": 5
}

4. List Files with Metadata

List files in a directory with detailed information:

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["list", ".", "--pattern", "*.py", "--recursive"]
}

Returns:

{
    "success": true,
    "files": [
        {
            "name": "orchestor.py",
            "path": "agent/orchestor.py",
            "size": 40960,
            "modified": "2024-01-21 10:30:00",
            "is_file": true
        }
    ]
}

5. Summarize Files (Smart Preview)

Best for: Getting overview of multiple files without reading full contents

Get file list with smart preview (first N lines only):

{
  "action": "call_skill",
  "skill": "file-ops",
  "tool_type": "script",
  "script": "file_ops_skill",
  "arguments": ["summarize", "--pattern", "**/*.py", "--preview-lines", "20", "--max-files", "50"]
}

Returns:

{
    "success": true,
    "summaries": [
        {
            "file": "agent/llm.py",
            "size": 743,
            "lines": 18,
            "encoding": "utf-8",
            "preview": "from openai import OpenAI\nclass LLMClient:\n    def __init__(self):\n..."
        },
        {
            "file": "agent/orchestor.py",
            "size": 41567,
            "lines": 1211,
            "encoding": "utf-8",
            "preview": "# -*- coding: utf-8 -*-\n...\n... (省略 1191 行)"
        }
    ],
    "total_files": 14,
    "pattern": "**/*.py"
}

Advantages:

• •90% faster than reading full files individually
• •95% less tokens (only preview first 20 lines)
• •Single command instead of N separate reads
• •Batch processing - one subprocess call for all files

Best Practices

When to Use File-Ops vs Shell

✅ Use File-Ops when:

• •Reading file contents (especially large files)
• •Finding files by pattern
• •Searching code/text across multiple files
• •Getting file metadata
• •You need fast, direct access without user interaction

❌ Use Shell when:

• •Running system commands (git, npm, docker)
• •Modifying files (use Write/Edit tools instead)
• •Complex shell pipelines
• •Platform-specific operations

Efficient Project Exploration

For "traverse project" tasks:

1. •List structure first: Use glob_files("**/*") to get overview
2. •Read selectively: Only read key files (main scripts, configs)
3. •Search when needed: Use search_files() to find specific patterns
4. •Avoid shell: Don't use Get-Content or cat in loops

Example workflow:

1. glob_files("**/*.py") → Get all Python files
2. read_file() on entry points (main.py, __init__.py)
3. search_files() to find specific classes/functions
4. Generate summary

Function Reference

read_file(path: str, encoding: str = "utf-8")

Read entire file contents.

Parameters:

• •path: File path (relative or absolute)
• •encoding: Text encoding (default: utf-8)

Returns: Dict with content, size, lines, encoding

glob_files(pattern: str, root_dir: str = ".")

Find files matching glob pattern.

Parameters:

• •pattern: Glob pattern (e.g., "**/*.py")
• •root_dir: Root directory to search from

Returns: Dict with list of matching files and metadata

search_files(pattern: str, path: str = ".", file_pattern: str = "*", max_matches: int = 100)

Search for regex pattern in files.

Parameters:

• •pattern: Regex pattern to search for
• •path: Directory to search in
• •file_pattern: File glob pattern to filter (e.g., "*.py")
• •max_matches: Maximum matches to return

Returns: Dict with matching lines and context

list_files(path: str = ".", pattern: str = "*", recursive: bool = False)

List files with metadata.

Parameters:

• •path: Directory path
• •pattern: Filename pattern (glob)
• •recursive: Include subdirectories

Returns: Dict with file list and metadata

Error Handling

All functions return a consistent format:

{
    "success": true/false,
    "error": "error message if failed",
    ... # additional result data
}

Common errors:

• •File not found
• •Permission denied
• •Encoding errors (automatically fallback to binary mode)
• •Path traversal attempts (blocked for security)

Implementation Notes

• •Uses Python's pathlib.Path for cross-platform paths
• •Implements security checks to prevent path traversal
• •Handles encoding errors gracefully (fallback to binary)
• •Efficient for large files (streaming reads available)
• •Thread-safe operations