spinosa-mapper

Extracts content-grounded fragments from raw files and writes Obsidian navigation maps.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large document collections are hard to navigate: researchers cannot quickly find which files discuss which concepts, and AI answers lose traceability to sources. This Skill batch-reads raw files, extracts grounded summaries, key passages, and concept signals, then builds Obsidian-linked navigation maps so every claim traces back to a file and line. ## Core Features & Use Cases - Batch Extraction: Reads raw files in batches and writes extraction packets with summaries, key passages with line references, concept signals, and Obsidian tags to agent_reports/extraction_{batch_id}.md. - Navigation Map Writing: Creates and enriches hub, group, and theme maps in maps/ using Obsidian wikilinks and hierarchical tags for graph-view filtering. - Idempotency & Safety: Skips already-processed batches, marks unreadable files, and enforces token limits for free-tier models. - Use Case: A social scientist with 200 interview transcripts runs the mapper to produce extraction packets and a corpus overview map linking every transcript to its themes and concepts. ## Quick Start Ask the agent to run a map_extract batch over the files in raw/ and write the extraction packet to agent_reports.

Frequently Asked Questions about spinosa-mapper

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

FAQPage Schema
How do I batch extract summaries and key passages from research documents?▼

Run a map_extract batch with a descriptive batch_id and a file list from the orchestrator. The agent reads each file completely and writes extraction packets with summaries, quoted key passages with line references, concept signals, and tags to agent_reports/extraction_{batch_id}.md.

How do I build Obsidian navigation maps from a document corpus?▼

Use the map_write phase after extraction batches exist. The agent reads all extraction packets, identifies natural groups and cross-cutting themes, and writes a hub map plus group and theme maps using wikilinks and hierarchical tags for Obsidian graph view.

Does the mapper skip files that were already processed?▼

Yes. Before extracting, it checks whether agent_reports/extraction_{batch_id}.md already exists with valid frontmatter and files_processed greater than zero. If so, it skips extraction and returns the existing path.

What happens when a file is unreadable or corrupt during extraction?▼

The file is skipped, marked as unreadable in the extraction packet's processed files table, and the batch continues with the remaining files. The unreadable count is reported back to the orchestrator.

What are the token limits when processing large batches?▼

Input plus cache must stay under 100k tokens for free-tier models like opencode/nemotron-3.5-lightning-free. If a batch would exceed this, process one to two files per turn or ask the orchestrator to split the batch.