Search Content Skill

Navigate and search the knowledge base efficiently using AkashicRecords directory governance structure.

When to use this Skill

• User asks "where is", "find", "search for"
• User queries file locations
• User looks for specific topics or content
• User needs to navigate knowledge base
• User asks "do I have notes about..."

Workflow

1. Analyze Query

Parse user request:

• Extract keywords and topics
• Identify search scope (specific directory or entire knowledge base)
• Determine search type (filename, content, topic, date-based)
• Assess query specificity (exact match vs fuzzy search)

Examples:

"Where are my transformer notes?" → Topic search, keyword: "transformer"
"Find files modified last week" → Date-based search
"Search for 'attention mechanism' in Research" → Content search, scoped to Research/
"List all meeting notes from October" → Category + date search

2. Choose Search Strategy

Select appropriate strategy based on query:

Strategy 1: Structured Navigation (Preferred)

When to use:

• Query mentions directory names (Work, Research, Personal, etc.)
• Looking for specific categories or types
• Query has clear organizational clues

Method:

• Start at root README.md or specified directory
• Follow directory index structure
• Use README.md files as curated navigation guides
• Narrow down systematically

Advantages:

• Fast and efficient
• Leverages existing organization
• Follows curated structure

Strategy 2: Pattern Search

When to use:

• Looking for filenames matching patterns
• User provides specific naming clues
• Need to find files by naming convention

Method:

• Use Glob for filename patterns: **/*keyword*.md
• Filter by date if needed: files modified in last N days
• Use multiple patterns for comprehensive search

Advantages:

• Direct filename matching
• Fast for filename-based queries
• Good for date-based searches

Strategy 3: Deep Content Search

When to use:

• Looking for specific text or code within files
• Pattern/structured search insufficient
• Need comprehensive text search

Method:

• Use Grep for content search: grep -r "keyword" .
• Search within specific file types
• Use Task subagent for complex multi-step searches

Advantages:

• Finds content regardless of organization
• Comprehensive coverage
• Good for forgotten file locations

3. Execute Search

Structured Navigation example:

User: "Find my AI research notes"

1. Start at root, read README.md
2. Identify Research/ directory (purpose: "Technical and academic research")
3. Read Research/README.md
4. Find AI/ or DeepLearning/ subdirectories
5. Read Research/AI/README.md
6. List all files in index
7. Filter by relevance
8. Return matching files

Pattern Search example:

User: "Find files about transformers"

1. Use Glob: `**/*transformer*.md`
2. Results:
   - Research/AI/2025-10-28-transformer-architecture.md
   - Research/AI/2025-10-20-transformer-applications.md
   - Work/Projects/transformer-project.md
3. Rank by modification date (most recent first)
4. Return results

Deep Content Search example:

User: "Search for 'attention mechanism'"

1. Use Grep: grep -r "attention mechanism" . --include="*.md"
2. Results (with context):
   - Research/AI/transformer-architecture.md (3 matches)
   - Research/AI/neural-networks.md (1 match)
3. Extract surrounding context for each match
4. Rank by relevance (match count, recency)
5. Return results with context snippets

4. Check Governance

For each result:

1. Check directory RULE.md for read permissions
2. Skip files in restricted directories
3. Note if file requires special access

Permission check:

RULE.md says: "Restricted access - confidential"
→ Skip this file or warn user about restrictions

Privacy considerations:

• Respect RULE.md access restrictions
• Don't expose content from restricted directories
• Warn if search includes restricted areas

5. Rank Results

Ranking criteria:

1. Relevance: Keyword matches, topic similarity
2. Recency: Recently modified files ranked higher
3. Location: Files in expected directories ranked higher
4. Completeness: README.md-indexed files ranked higher (curated)

Scoring example:

File A: transformer-architecture.md
- Title match: +50
- Recent (3 days): +30
- In expected directory (Research/AI): +20
- Listed in README: +10
- Total: 110

File B: old-notes.md
- Content match only: +30
- Old (3 months): +5
- In Miscellaneous: +10
- Not in README: +0
- Total: 45

Result order: File A, then File B

6. Present Results

Clear result format:

📚 Search results for "[query]"

Found [X] matches:

1. [filename.md](path/to/file.md) ★★★★☆
   Location: [directory path]
   Last modified: [date]
   Description: [from README.md or first line]
   Match: [Context snippet if content search]

2. [another-file.md](path/to/another.md) ★★★☆☆
   Location: [directory path]
   Last modified: [date]
   Description: [description]
   Match: [Context snippet]

[More results...]

Didn't find what you need?
- Try broader keywords
- Search in specific directory
- Check Archive/ for old content

Include helpful metadata:

• File location (full path)
• Last modified date
• Brief description from README.md
• Relevance score (stars or percentage)
• Context snippet (for content searches)

7. Follow-up Options

After presenting results:

What would you like to do?
- Read [filename]
- Search within these results
- Refine search with different keywords
- Search in different directory
- Show more results

Interactive refinement:

• User can narrow down results
• Ask follow-up questions
• Navigate to related files
• Explore directory structure

Search Strategies in Detail

Structured Navigation

Step-by-step process:

1. Identify starting point (root or specific directory)
2. Read starting README.md
3. Parse directory structure from README.md
4. Match query keywords to directory names/descriptions
5. Descend into most relevant subdirectory
6. Repeat until finding target files
7. List files from README.md index

Example:

Query: "Find meeting notes from October"

1. Read root README.md
2. Find Work/ directory
3. Read Work/README.md
4. Find Meetings/ subdirectory
5. Read Work/Meetings/README.md
6. Filter entries by date (October)
7. Return matching files

Advantages:

• Leverages human-curated organization
• Fast and efficient
• Follows logical structure

Limitations:

• Requires good README.md maintenance
• May miss files not indexed
• Depends on consistent organization

Pattern Search

Glob patterns:

**/*keyword*.md           → Find files with "keyword" in name
**/*YYYY-MM-DD*.md       → Find files with specific date format
Research/**/*.md          → Find all markdown in Research/
Work/Projects/**/*.md     → Find all markdown in Work/Projects/

Advanced patterns:

**/{transformer,attention,neural}*.md  → Multiple keywords
**/*2025-10*.md                        → October 2025 files
**/*.{md,txt}                          → Multiple extensions

Date-based search:

# Files modified in last 7 days
find . -name "*.md" -mtime -7

# Files modified in October 2025
find . -name "*2025-10*.md"

Advantages:

• Direct filename matching
• Fast execution
• Good for date/name patterns

Limitations:

• Only searches filenames
• Misses content matches
• Requires knowing naming conventions

Deep Content Search

Grep search:

# Basic content search
grep -r "keyword" . --include="*.md"

# Case-insensitive
grep -ri "keyword" . --include="*.md"

# Multiple keywords (OR)
grep -rE "keyword1|keyword2" . --include="*.md"

# With context lines
grep -r "keyword" . --include="*.md" -A 2 -B 2

Task subagent for complex searches:

User: "Find all notes about transformers that mention attention mechanism and were created in the last month"

→ Too complex for single grep
→ Invoke Task subagent:
  1. Grep for "transformer"
  2. Filter results by "attention mechanism"
  3. Filter by date (last month)
  4. Return consolidated results

Advantages:

• Comprehensive text search
• Finds content regardless of location
• Good for forgotten file locations

Limitations:

• Slower than other methods
• May return too many results
• High context consumption (use Task subagent for complex cases)

Search Optimization

Start Specific, Expand if Needed

Progression:

1. Try structured navigation first (if logical directory exists)
2. If no results: try pattern search
3. If still no results: try deep content search
4. If still nothing: suggest broader keywords or check Archive/

Example:

Query: "Find transformer notes"

1. Structured: Check Research/AI/README.md → Found 2 files ✅
2. Pattern: Not needed (found with structured)
3. Content: Not needed

vs.

Query: "Find notes about neural attention"

1. Structured: Check Research/AI/README.md → No exact match
2. Pattern: **/*attention*.md → Found 1 file
3. Content: grep "neural attention" → Found 3 more files
4. Combined results, ranked by relevance

Use README.md as Primary Index

README.md advantages:

• Curated by user (most important files listed)
• Includes descriptions (better context)
• Organized logically (related files grouped)
• Faster than filesystem traversal

Always check README.md first before deep searches.

Minimize Context Consumption

For simple searches:

• Use Glob/Grep directly
• Return results without reading full files
• Only read files user wants to open

For complex searches:

• Use Task subagent to handle complexity
• Subagent consumes context, not main agent
• Return only summarized results to user

Error Handling

No Results Found

Query: "Find transformer notes"
→ No matches in any strategy

→ Response:
"I couldn't find notes about transformers.

Suggestions:
- Try broader keywords (AI, neural networks)
- Search in Archive/ for old content
- Check if files use different terminology
- Create new note if content doesn't exist"

Too Many Results

Query: "Find notes"
→ Returns 500+ matches

→ Response:
"Found 500+ files matching 'notes'.

Please narrow your search:
- Add more specific keywords
- Specify directory (Research, Work, Personal)
- Add date filter (from last week, October, etc.)
- Provide more context about what you're looking for"

Ambiguous Query

Query: "Find it"
→ Query too vague

→ Response:
"Could you provide more details?

What are you looking for?
- File name or topic keywords
- Approximate date or time period
- Which directory (Research, Work, etc.)
- Type of content (meeting notes, research, etc.)"

Permission Denied

Search encounters restricted directory
RULE.md: "Access restricted"

→ Skip directory in results
→ Note: "Some directories were excluded due to access restrictions"

Integration with Governance

This Skill respects directory governance:

Before searching:

• Check RULE.md for search permissions
• Respect access restrictions
• Note privacy constraints

During search:

• Skip restricted directories
• Follow governance rules
• Maintain confidentiality

In results:

• Only show accessible files
• Note if restricted areas skipped
• Respect RULE.md read permissions

Examples

Example 1: Topic Search

User: "Where are my transformer architecture notes?"

Skill workflow:

1. Analyzes query → Topic: transformer architecture
2. Chooses structured navigation (research topic)
3. Reads root README.md → Finds Research/
4. Reads Research/README.md → Finds AI/
5. Reads Research/AI/README.md
6. Finds 2 matches:
   • transformer-architecture.md (3 days ago)
   • transformer-applications.md (2 weeks ago)
7. Ranks by recency
8. Presents results with descriptions

Example 2: Date-Based Search

User: "Find my meeting notes from last week"

Skill workflow:

1. Analyzes query → Category: meetings, Date: last week
2. Chooses structured navigation + date filter
3. Reads root README.md → Finds Work/
4. Reads Work/README.md → Finds Meetings/
5. Reads Work/Meetings/README.md
6. Filters entries by date (last 7 days)
7. Finds 3 meetings
8. Presents chronologically

Example 3: Content Search

User: "Search for 'attention mechanism' in my notes"

Skill workflow:

1. Analyzes query → Content search, keyword: "attention mechanism"
2. Chooses deep content search
3. Executes: grep -ri "attention mechanism" . --include="*.md"
4. Finds 5 matches across 3 files
5. Extracts context snippets
6. Checks RULE.md permissions for each file
7. Ranks by relevance (match count + recency)
8. Presents with context snippets

Best Practices

1. Start with structured navigation - Fastest and most relevant
2. Use README.md indexes - Curated by user, most important
3. Minimize context - Don't read files unless needed
4. Rank results meaningfully - Relevance + recency + location
5. Provide context - Show why files matched
6. Offer follow-up - Help user refine search
7. Respect governance - Check RULE.md permissions
8. Handle edge cases - No results, too many results, ambiguous queries

Notes

• This Skill works with any directory structure
• Leverages README.md indexes for curated navigation
• Uses multiple search strategies for comprehensive coverage
• Respects RULE.md governance and access restrictions
• Minimizes context consumption with Task subagent for complex searches
• Works in parallel with CLAUDE.md subagents independently
• Provides interactive refinement for better results