text-scan

Quickly find and score relevant lines with context in large text files using keyword and phrase matching to minimize reading entire files.

Security Scan

The skill is internally consistent with a local text-scanning utility: it reads files, scores matching lines, and has no network, credential, or install requirements.

Purpose & Capability

The included Python script implements token/phrase scoring and returns context lines, which matches the skill description. Minor mismatches: SKILL.md advertises a '--fuzzy' fuzzy-matching mode and a behavior 'If no --query is given, reads from stdin for the query', but the script accepts a --fuzzy flag without implementing fuzzy logic and in practice requires --query (the code never treats a missing query specially). Examples reference a specific user home path (/home/marek), which is harmless but should be generalized.

Instruction Scope

Runtime instructions and the script operate only on local files or stdin, and only read/emit file contents. There are no instructions to read unrelated system state, environment variables, or send data externally.

Install Mechanism

No install spec; this is an instruction-only skill with a small bundled script. Nothing is downloaded or executed from external sources during install.

Credentials

The skill requires no environment variables, credentials, or config paths. The example file paths are local and match the stated purpose.

Persistence & Privilege

The skill does not request persistent presence (always is false) and does not modify other skills or system configuration. It runs on demand and only accesses files the user gives it.

Assessment

This is a simple, local text-scanning utility and appears to do what it says: read files (or stdin) and return scored matches with context. Before installing/running, note these points: (1) the tool will print matched lines and context to stdout or to an output file you specify — do not run it against files containing secrets unless you want that content displayed/stored; (2) the SKILL.md mentions fuzzy matching and a stdin-query mode that are not actually implemented in the script — expect the --fuzzy flag to do nothing and --query to be required; (3) examples use a hardcoded user path (/home/marek) — replace with your own paths. If you need fuzzy matching or different query/stdin behavior, review or modify the script source before use.

Description

Search for relevant information in text files without reading the entire file. Returns matching lines with context, scored by relevance. Useful for quickly finding specific information in large files.

When to Use

• You need to find a specific piece of information in a file but don't know the exact location
• You want to scan multiple files for relevant content before deciding which to read fully
• Marek wants you to extract specific lines from large files
• You're doing research and need to quickly scan through notes, logs, or documents
• The file is very large and reading it entirely would waste tokens/time

How It Works

The script uses token-based matching with scoring:

• Exact token matches score 2 points
• Substring/partial matches score 1 point
• Phrase matches (adjacent query terms found together in the line) score 3 points
• Results are sorted by score and limited

Usage

# Basic search
python3 <skill_dir>/scripts/text-scan.py <file> --query "<search terms>"

# Brief format (line number + content)
python3 <skill_dir>/scripts/text-scan.py <file> --query "<search terms>" --brief

# JSON output (for programmatic use)
python3 <skill_dir>/scripts/text-scan.py <file> --query "<search terms>" --json

# Custom context window
python3 <skill_dir>/scripts/text-scan.py <file> --query "<search terms>" --before 3 --lines 5

# From stdin
cat <file> | python3 <skill_dir>/scripts/text-scan.py --query "<search terms>"

Examples

# Find the runway in STATE.md
python3 <skill_dir>/scripts/text-scan.py /home/marek/.openclaw/workspace/STATE.md --query "runway"

# Find today's work hours
python3 <skill_dir>/scripts/text-scan.py /home/marek/.openclaw/workspace/STATE.md --query "today work hours"

# Find all log entries about a topic
python3 <skill_dir>/scripts/text-scan.py /home/marek/.openclaw/workspace/LOG.md --query "weather"

Parameters

Parameter	Description	Default
--query, -q	Search query (keywords)	required
--lines, -a	Lines after each match	5
--before, -b	Lines before each match	2
--max-results, -n	Maximum results to return	5
--json	JSON output format	false
--brief	Brief format only	false
--fuzzy	Enable fuzzy matching	false
--output, -o	Write results to file	stdout

Integration with OpenClaw

This skill integrates with the standard read tool workflow:

1. Use text-scan to quickly find relevant lines in a file
2. If the result is significant, use read to load the full file context
3. This reduces token usage by avoiding reading unnecessary content

Tips

• Use shorter queries for broader matches, longer phrases for precision
• The --brief flag is fastest for quick scans
• --json output is useful for scripting/automation
• Combine with find to scan multiple files: find . -name "*.md" | xargs ...
• Score 3+ matches are usually high-confidence — worth reading in full