mbailey/sqldown

Overview

This skill provides bidirectional conversion between markdown and SQLite so you can query your docs with SQL and export results back to markdown. It loads markdown files into a dynamic SQLite schema with YAML frontmatter and H2 section extraction, while protecting against SQLite column limits. Use sqlite3 directly for queries and sqldown for import, dump, and info operations.

How this skill works

sqldown scans markdown files recursively, parses YAML frontmatter into columns, and extracts H2 sections as section_* columns. It builds a dynamic schema and upserts rows idempotently into an SQLite file, applying .gitignore filtering and optional watch mode. Column-limit protection analyzes section frequency and keeps only the top N sections as separate columns; remaining content stays in the body field.

When to use it

• You need SQL-powered filtering, aggregation, or joins over many markdown files
• You maintain structured markdown with YAML frontmatter and repeatable H2 sections
• You want a lightweight, local index for fast metadata queries and progressive disclosure
• You need to export filtered database rows back into markdown files
• You want automatic, idempotent caching of documents with optional auto-refresh

Best practices

• Start by inspecting the table schema with sqlite3 ".schema <table>" to see available columns
• Use metadata-only queries first (title, _path, status) and read full files only when needed
• Adjust --top-sections to control how many H2 sections become queryable columns
• Keep related document types in separate tables to simplify schemas and queries
• Use watch mode during active editing and one-time loads for scheduled updates

Example use cases

• Index a notes or tasks directory and run SQL reports like counts by status or recent updates
• Search across diverse docs with body LIKE or FTS5 after loading content into SQLite
• Export a filtered subset (e.g., active tasks) back to markdown with sqldown dump
• Maintain a live cache of documentation while developing by running sqldown load --watch
• Combine multiple tables (tasks, notes, skills) and query across them with UNION ALL