cleveragents-core/docs/reference/skills_search.md

Search and Directory Skills

Skill-level directory listing and search tools for agents. All tools enforce path traversal guards and provide deterministic, sorted output.

Tools

Tool	Capability	Description
skill/list-dir	read_only	List directory with filters, limits, type filtering
skill/glob	read_only	Match files by glob with include/exclude filters
skill/grep	read_only	Search contents by regex with context lines

ListDir

Lists directory contents with:

• Ignore patterns: Glob patterns to exclude entries.
• Type filter: Show only files, only directories, or all.
• Size limit: Cap the number of entries returned.

Example

from cleveragents.skills.builtins.search_ops import register_skill_search_tools
from cleveragents.tool.registry import ToolRegistry
from cleveragents.tool.runner import ToolRunner

registry = ToolRegistry()
register_skill_search_tools(registry)
runner = ToolRunner(registry)

result = runner.execute("skill/list-dir", {
    "path": "src",
    "type_filter": "files",
    "ignore_patterns": ["__pycache__", "*.pyc"],
    "sandbox_root": "/project",
})
for entry in result.output["entries"]:
    print(f"{entry['name']} ({entry['size']} bytes)")

Glob

Matches files recursively by glob pattern with:

• Exclude patterns: Filter out unwanted matches.
• Include patterns: Restrict matches to specific names.
• Deterministic sorting: Results are always sorted by path.
• Size limit: Cap the number of matches returned.

Example

result = runner.execute("skill/glob", {
    "path": ".",
    "pattern": "**/*.py",
    "exclude_patterns": ["test_*"],
    "sandbox_root": "/project",
})

Grep

Searches file contents with regex:

• Context lines: Include N lines before and after each match.
• Binary file skipping: Binary files are automatically skipped.
• Per-file match cap: Limit matches per file (default: 50).
• Total match limit: Overall cap on matches (default: 500).
• Regex error handling: Invalid patterns produce clear error messages.

Example

result = runner.execute("skill/grep", {
    "path": "src",
    "pattern": "def\\s+\\w+",
    "include": "*.py",
    "context_lines": 2,
    "sandbox_root": "/project",
})
for match in result.output["matches"]:
    print(f"{match['file']}:{match['line']}: {match['content']}")

Regex Error Handling

When an invalid regex pattern is provided, Grep returns a clear error:

ValueError: Invalid regex pattern '[unclosed': unterminated character set

Binary File Behavior

Grep automatically detects and skips binary files using the same heuristics as the ReadFile tool (signature detection + control character analysis). Binary files are silently excluded from results.