AgentSkillsCN

batch-read

一次操作即可查找并读取多个文件（探索效率提升 50%-70%）

SKILL.md
--- frontmatter
name: batch-read
description: Find and read multiple files in one operation (50-70% faster for exploration)
allowed-tools: Bash

Batch Read Skill

Purpose: Find files matching a pattern and read them in a single atomic operation, reducing LLM round-trips from 1+N to 2-3.

Performance: 50-70% faster for reading 3+ files during codebase exploration

When to Use This Skill

Use batch-read When:

  • •Exploring codebase to understand how a feature works
  • •Finding examples of a pattern across multiple files
  • •Gathering context for a code change
  • •Reviewing implementations of similar functionality
  • •Understanding usage of a particular API or method
  • •Reading related configuration files
  • •Collecting test examples from multiple test files

Do NOT Use When:

  • •Reading specific known files (use Read tool directly)
  • •Need to read entire large files (>1000 lines each)
  • •Files are unrelated (no common pattern)
  • •Need precise file selection (specific paths known)
  • •Reading binary files or generated code
  • •Files require deep analysis (better to read individually)

Performance Comparison

Traditional Workflow (1+N LLM round-trips, 10s + 5s*N)

code
[LLM Round 1] Search for pattern
  -> Grep: Find files containing "FormattingRule"
  -> Returns: file1.java, file2.java, file3.java

[LLM Round 2] Read first file
  -> Read: file1.java

[LLM Round 3] Read second file
  -> Read: file2.java

[LLM Round 4] Read third file
  -> Read: file3.java

[LLM Round 5] Analyze and report
  -> Summarize findings from all files

Total: 10s + (5s * 3) = 25s, 5 LLM round-trips

Optimized Workflow (2-3 LLM round-trips, 8-12s)

code
[LLM Round 1] Execute batch-read
  -> Bash: batch-read.sh "FormattingRule" --max-files 3
  -> [Script finds files + reads all + returns content]

[LLM Round 2] Analyze and report
  -> Parse combined output
  -> Summarize findings

Total: 8-12s, 2-3 LLM round-trips

Savings: 50-70% faster for N>=3 files

Usage

This skill uses inline Bash commands - no external script required.

Basic Pattern Search

bash
# Find and read files containing "FormattingRule"
# Step 1: Find files
FILES=$(grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -5)
# Step 2: Read each file with line numbers
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; done

With File Type Filter

bash
# Only search Java files
grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -5

Limit Results

bash
# Read at most 3 files
FILES=$(grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -3)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; done

Control Output Size

bash
# Show only first 50 lines of each file
FILES=$(grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -50; done

Read Entire Files

bash
# Read complete files (no truncation)
FILES=$(grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f"; done

Combined Options

bash
# Search Java files, read 5 files, show 100 lines each
FILES=$(grep -rl "FormattingRule" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; echo "---"; done

Output Format

The inline bash commands produce combined file contents:

code
===============================================================
FILE: src/main/java/FormattingRule.java
===============================================================

     1  package io.github.cowwoc.styler;
     2
     3  public interface FormattingRule {
     4      void apply(StyleContext context);
     5  }

[... file content ...]

---------------------------------------------------------------

===============================================================
FILE: src/test/java/FormattingRuleTest.java
===============================================================

     1  package io.github.cowwoc.styler;
     2
     3  import org.testng.annotations.Test;
     4
     5  public class FormattingRuleTest {
     6      @Test
     7      public void testRule() {
     8          // Test implementation
     9      }
    10  }

[... file content ...]

---------------------------------------------------------------

Common Use Cases

1. Understanding Feature Implementation

bash
# Find all files implementing a specific feature
FILES=$(grep -rl "ValidationEngine" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; done

2. Reviewing Test Coverage

bash
# Find all test files for a component
FILES=$(grep -rl "FormatterTest" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; done

3. Finding Usage Examples

bash
# See how an API is used across the codebase
FILES=$(grep -rl "StyleContext.apply" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do echo "=== $f ==="; cat -n "$f" | head -100; done

4. Configuration Review

bash
# Review all configuration files
find . -name "*.properties" -o -name "*.yml" 2>/dev/null | head -10 | while read f; do
  echo "=== $f ==="; cat -n "$f"; done

5. Documentation Gathering

bash
# Collect all README files
find . -name "README*.md" 2>/dev/null | head -20 | while read f; do
  echo "=== $f ==="; cat -n "$f"; done

Smart Filtering Features

Automatic Deduplication

Using grep -l (list files only) avoids duplicate results from multiple matches in same file.

Line Number Preservation

Using cat -n includes line numbers to help locate code:

code
     42  public void validate() {
     43      // Implementation
     44  }

Truncation Indication

Use head -N to limit output lines per file:

bash
cat -n "$f" | head -100  # First 100 lines only

Size Warnings

For large codebases, limit file count and lines per file:

bash
# Limit to 5 files, 50 lines each
FILES=$(grep -rl "pattern" . --include="*.java" 2>/dev/null | head -5)
for f in $FILES; do cat -n "$f" | head -50; done

Performance Characteristics

Time Savings by File Count

FilesTraditionalOptimizedSavings
1 file15s10s33%
2 files20s10s50%
3 files25s11s56%
5 files35s12s66%
10 files60s15s75%

Frequency and Impact

Expected Usage: 5-10 times per day

Time Savings per Use: ~15-30 seconds (average 3-5 files)

Daily Impact: 75-300 seconds (1.25-5 minutes)

Monthly Impact: 30-150 minutes (0.5-2.5 hours)

Limitations

File Size Limits

  • •Default: 100 lines per file
  • •Can read entire files with --context-lines 0
  • •Large files (>1000 lines) may produce too much output

Pattern Matching

  • •Uses grep regex (not fuzzy matching)
  • •Case-sensitive by default
  • •Searches file contents, not file names

File Type Detection

  • •--type filter uses file extension only
  • •Example: --type java matches *.java files
  • •Does not inspect file contents for type detection

When NOT to Use

Known Specific Files

Wrong: Use batch-read to find and read one known file

bash
grep -rl "MyClass" . | xargs cat  # Overkill for one file

Correct: Use Read tool directly

code
Read: /path/to/project/src/main/java/MyClass.java

Unrelated Files

Wrong: Read random files that happen to match pattern

bash
grep -rl "test" .  # Too generic, matches everything

Correct: Use specific pattern or file type

bash
grep -rl "ValidationTest" . --include="*.java" | head -5

Deep Analysis Needed

Wrong: Read 10 large files for detailed analysis Correct: Read files one-by-one for thorough review

Related

  • •Read tool: For reading specific known files
  • •Grep tool: For finding files without reading them
  • •Glob tool: For finding files by pattern (name-based)