spinosa-searcher

Searches document corpora with grep and writes structured evidence packets to files.

7|Updated May 13, 2026
One-click install
npx skills add https://github.com/medialab/spinosa --skill spinosa-searcher-medialab
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spinosa-searcher
Source: https://github.com/medialab/spinosa/tree/main/workspace-template/.opencode/skills/spinosa-searcher
Command: npx skills add https://github.com/medialab/spinosa --skill spinosa-searcher-medialab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Finding grounded evidence across large collections of documents (interviews, PDFs, transcripts, notes) is slow and error-prone, and AI answers often lack traceable sources. This Skill systematically searches a raw corpus using maps and a term dictionary, then writes every finding to a citable evidence packet file. ## Core Features & Use Cases - Guided corpus navigation: Reads a term dictionary and structural maps before searching, expanding queries with synonyms, grammatical forms, and colloquial-to-technical term bridging. - Bounded iterative search: Runs up to 5 grep rounds with early-stop conditions (sufficient evidence, diminishing returns, token budget) and decomposes complex comparative queries into sub-queries. - Structured evidence packets: Writes findings to agent_reports/ files with YAML frontmatter tracking sources, confidence levels, navigation paths, and search termination reasons. - Use Case: A researcher asks "What causes geomagnetic reversals?" across a folder of earth science notes; the Skill consults the dictionary, searches the corpus, and returns a file path to an evidence packet with quoted excerpts and confidence ratings. ## Quick Start Ask the agent to search the workspace corpus for evidence on your research question and return the path to the written evidence packet.

Frequently Asked Questions about spinosa-searcher

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search a large document corpus for evidence with an AI agent?▼

Use grep for content search and glob only for file discovery, guided by a term dictionary and structural maps. Expand queries with synonyms and grammatical forms, then write matched excerpts with confidence ratings to an evidence packet file.

How to handle complex comparative search queries across documents?▼

Decompose queries containing "vs", "compare", or multiple joined topics into 2-4 independent sub-queries. Search each sub-query separately, then merge results into one evidence packet with a decomposition entry listing sub-queries and their sources.

When should a corpus search stop iterating?▼

Stop when at least 2 high-confidence sources are found, when the last 2 rounds add no new files, when 1000 lines have been read, or after 5 rounds maximum. Record the termination reason in the evidence packet frontmatter.

What are the limitations of grep-based document search?▼

Grep matches literal text patterns, so it misses semantically related content phrased differently. Mitigate this by expanding terms with synonyms, word stems, and colloquial-to-technical mappings from the dictionary before searching.

Why write search results to files instead of returning them inline?▼

Large evidence lists exceed context limits and are hard to audit. Writing packets to agent_reports/ files keeps responses small, makes findings inspectable, and lets orchestrator agents consume results via file paths.