duckstack

Alok's DuckDB skills for the duckstack: one persistent DuckDB per machine (~/.duck/dev.duckdb) held locked by an always-on server, agents as stateless :memory: clients, the dev MCP as the agent door, and his SQL process rules. The server itself is in this repo — server/setup.sql, which ~/.duck/setup.sql links to. The style guide is his own repos (duckdb-ops-toolkit conduit, duckdb-chrome-bridge, claudes-console, takehome-granica); upstream duckdb/duckdb-skills is reference material, not a base.

There is deliberately no state.sql, no -init, no ATTACH to the server: the persistent state is the server. An agent reaches it through the dev MCP (query, sql, and the task tools), POST localhost:9495/sql, or quack_query('quack:localhost:9494', $$…$$, token := getenv('QUACK_TOKEN')) from its own duckdb :memory: — see /duckstack:agent-door. -c, -f and -cmd keep ~/.duckdbrc (the resource floor); -init replaces it.

Skills

Generated from each skills/*/SKILL.md frontmatter (read_yaml_frontmatter('skills/*/SKILL.md') → COPY … (FORMAT markdown)); regenerate it the same way when a description changes.

Skill	What it is for
agent-dispatch	Use before fanning work out to subagents in this user's repos. Encodes his written orchestration practices (private repo asubbarao/devx-takeaways, agent-orchestration/) as a dispatch packet plus the house rules every worker must carry: Opus 5.5 set explicitly unless a model is named (say which and why), no .sh or Python in the data path (shellfs inside .sql), regex only on web and log text, no selector-taking extractors, no lossy aggregation, and evidence that is false-first and read from CI/GitHub. Covers launch-evidence-before-promotion, write-scope as an enforcement boundary, bounded rounds, and recombination.
agent-door	How any agent reaches the dev DuckDB — the one always-on database on this machine. Three doors, one database, no attach: the dev MCP (query, sql tools), POST localhost:9495/sql, or quack_query from your own :memory: DuckDB. Also the task tools: git_tree and git_read (a repo through duck_tails), ci_hunt (an Actions log zip through duck_hunt), render (a tera template to a file), ext_docs, and the agent-stream tools. Use before the first statement that touches dev, when a tool or port in your notes no longer answers, or when an agent without MCP needs to run SQL on dev.
agent-log	Log what you did as parquet, in one call (a COPY through the dev MCP sql tool), so a human can read every agent's work in SQL. Use whenever you run a query or a program worth keeping, and whenever you dispatch subagents — they call this themselves, you do not collect their output. One call per artifact: the same token is stored as text and executed, so the result cannot be invented; a crash is a row, not a lost turn. FILENAME_PATTERN '{uuid}' makes n writers into one directory safe with no lock. Works the same for SQL, Python, .bat or any other language.
agent-stream	Search and read every agent conversation on this machine — Claude Code, Claude Desktop, Codex — as one table on dev, refreshed every 5 minutes. Use when asked to find a past conversation ("the codex chat about X", "what did I say about Y"), to read what the user typed recently, to continue earlier work, or to check what an agent actually ran. MCP tools: stream_search, stream_session, user_messages. Never grep transcript files or read ~/.claude by hand.
ci-timing	GitHub Actions timing as tables — where CI minutes go, read from GitHub so anyone with gh access can re-run it. gh run list/view --json and gh api (a PR's files, a run's log zip) through shellfs, every response landed under raw/ with a UTC timestamp, then runs / jobs / steps / PR-files tables and the questions that matter: the long pole, setup vs suite inside a job, whether the change-detection gate runs jobs a PR did not need, and whether test shards are balanced. It is the CI/CD analysis: test-level times and failures come from the job logs through duck-hunt's recipe views, and live-page renders the result. Use when asked why CI is slow, what a run or shard spends its time on, for a CI or PR review page, a brief page on one CI finding, or any timing evidence a teammate may see. Never use local logs. Worked examples: ~/inframe/internal/ci/duckdb/ (review.sql, slow.sql) and the INF-1390 shard brief (§5).
convert-file	Convert any data file to another format: CSV, Parquet, JSON, Excel, GeoJSON, and more. Use when the user says "convert to parquet", "save as xlsx", "export as JSON", "make this a CSV", "turn into parquet", or any variation of format-to-format conversion for data files. Also triggers when the user wants to write Parquet, Excel, or other binary formats that Claude cannot produce natively.
crawl	Pages as tables. crawler × webbed on the dev quack for anything a plain HTTP fetch can reach; the logged-in Chrome (duckdb-chrome-bridge) for SPAs and authenticated pages. Use when the user says crawl, scrape, fetch these URLs, hit these links, get the page, read the docs at, or gives URLs to read. States every crawl() parameter, lands the raw response first, parses by the capability ladder — never regex, never uncorrelated laterals, never an error page as a seed, never chrome_open to read.
duck	The DuckDB execution boundary and SQL process rules for this machine — read before any DuckDB work. One persistent dev DuckDB is held locked by a quack server; every agent is a stateless :memory: client that LOADs quack and talks to it — one statement, or one .sql artifact. Use whenever a task touches DuckDB, the duckstack, quack, the dev MCP, crawler/webbed, Chrome-as-relations, or when an agent is about to write SQL for this user. Every other duckdb-skills skill assumes this one.
duck-hunt	Test results, build output, lint output and CI job logs as tables ("readable CI"). duck_hunt parses 110 tool formats and GitHub Actions / GitLab / Jenkins / Docker workflow logs into one 40-column event schema (status, severity, ref_file, ref_line, test_name, fingerprint, …). Ships a growing library of tested views in recipes.sql: pytest_xdist_tests, vitest_files, vitest_phases, gha_steps, gha_errors, biome_diagnostics, failure_clusters, recurring_diagnostics. Every CI/CD analysis adds its new readings there and its new gotchas to Learned. Use when asked why CI is red, what a run's tests did, to diff two runs, to cluster failures by fingerprint, to find failures that recur across runs, to land a job log as rows, or to time tests from a log that prints no durations. Regex on log text is allowed. Pairs with ci-timing (runs, jobs, steps), duck_tails (blame the ref_file:ref_line the parser points at) and live-page (render the result).
duck-tails	A git repository as a filesystem, not just as a log. LOAD duck_tails registers the git:// filesystem, and every DuckDB reader works over it — including Parquet (verified: 66 hive-partitioned Parquet blobs read straight out of a commit, hive keys intact, parquet_metadata and all). The history tables (git_log, git_tree, git_read, git_status, blame, diffs) are the other half. Use when asked to read a repo at a revision, read data committed to a repo, compare a dataset across commits, inventory what a repo contains, or when about to shell out to git show/git archive, gh api or curl to get a file's bytes — including a file in a GitHub repo, which is git clone --bare first, then read here (dev MCP tools: git_tree, git_read). Read /duckstack:duck first — its SQL process rules apply to git data too.
duckdb-docs	Search DuckDB and DuckLake documentation and blog posts. Returns relevant doc chunks for a question or keyword using full-text search against a locally cached index.
ducklake	Landing raw pulls in a DuckLake so a re-pull is a snapshot instead of an overwrite, and reaching a DuckLake catalog from this machine. Use when attaching a lake, when an insert produces a lake with no parquet in it, when a ducklake: ATTACH fails, when asked to backfill or re-pull a window, or when deciding where a raw table should live.
ext-catalog	The DuckDB community extension catalog on dev — every extension's community page, README and function tables, parsed into rows. Use before using an extension you have not used today, when asked what an extension does or which functions/settings/parameters it has, when choosing an extension for a job, or when the user half-remembers a name ("mini something", "the js one") — find it with contains() on agents.ext_catalog, never by guessing or web search. MCP tool: ext_docs. Read this instead of guessing parameters or fetching the docs site.
git-github	Git history and GitHub as tables — "readable git". duck_tails for any local repository (git_log, git_tree, git_read, git_status, blame, diffs, git:// paths at any revision), the gh extension for public GitHub metadata and gh:// file reads, and the gh CLI (authenticated) for private repos and raw file contents landed into DuckDB. Use when asked to read a repo, look at what changed, hit a GitHub URL, list issues/PRs, or compare files across commits.
install-duckdb	Install or update DuckDB extensions. Each argument is either a plain extension name (installs from core) or name@repo (e.g. magic@community). Pass --update to update extensions instead of installing.
live-page	Make a web page fast with DuckDB alone: tera for the HTML, quickjs for SVG charts (any JS), crawler's css_select to check, pull or serve one block of HTML, jsonata to reshape rows into the page's JSON. It writes one self-contained .html (opens from file://, uploads to Slack) and can serve it live through quackapi, so each browser refresh re-runs the SQL. Use for any HTML page, analysis page, writeup, report, one-pager, dashboard, "chart that", comparison with charts, "zeroload" page, "liverender" / live-render page or live page, whatever the data source: a CLI or API through shellfs, a read-only Postgres, crawled web pages, or files. Short verified snippets, not templates; the analysis supplies the data and the words (e.g. ci-timing for CI/CD).
markdown	Read, analyze, convert, or emit Markdown with DuckDB's markdown extension. Reach for this when .md files, Markdown text, headings, sections, code blocks, links, tables, frontmatter, or conversion to typed document blocks are the data source.
parser_tools	Validate SQL and inspect its parsed tables, functions, statements, and WHERE conditions with DuckDB's native parser. Reach for this when SQL text or extracted code blocks must be structurally classified without regex, keyword matching, or executing the SQL.
pdf	PDFs as tables, with the pdf community extension — never poppler CLI, pypdf, pdfplumber or any Python library. Use when the user gives a .pdf path or URL, says read/extract/parse this PDF, asks what a document says, wants its tables, forms, metadata, signatures or page images, or wants a PDF merged, split, rotated, redacted or written. Reads at five grains (page, line, word+bbox, layout element, retrieval chunk) and renders pages to PNG without pdftoppm.
quack	How to call the Quack server: quack_query, one complete body, no attach. Use before any statement that touches the server, when a table "does not exist", when a join fails with "Multiple streaming scans", or when reaching for ATTACH / .read / SET VARIABLE to set up.
query	Run SQL on the dev quack (or another explicitly selected door) or ad-hoc against files. Accepts raw SQL, a natural-language question, or a path to a .sql artifact. One statement runs with duckdb :memory: -c; anything longer is a single .sql artifact run by path with -f — no state file, the ATTACH is in the head. Uses DuckDB Friendly SQL and this user's SQL process rules; --# lines in an artifact are the human's instructions.
read-file	Read any data file (CSV, JSON, Parquet, Avro, Excel, spatial, SQLite, Markdown, YAML, HTML, XML, PDF) or remote URL (S3, HTTPS). For deeper PDF work (multiple grains, OCR, forms, redaction, writing) use /duckstack:pdf instead. Use when user references a data file, asks "what's in this file", or wants to preview/profile a dataset. Not for source code.
read-memories	Search past Claude Code session logs to recall prior decisions, patterns, or unresolved work. Use when user says "do you remember", "what did we do", references past conversations, or you need context from prior sessions.
s3-explore	Explore and query data on S3, Cloudflare R2, GCS, MinIO, or any S3-compatible storage. Use when the user mentions an s3://, r2://, gs://, or gcs:// URL, asks "what's in this bucket", wants to list remote files, preview remote Parquet/CSV/JSON, or query data on object storage without downloading it. Also triggers when the user wants to know the size, schema, or row count of remote datasets.
self-dispatch	Self-dispatch — the database writes the statement it cannot bind, then runs it. Use whenever a table function (glob, ls, lsr, read_text, read_csv, read_blob, crawl, quack_query, query) needs a value that lives in a column ("does not support lateral join column parameters"), whenever work must fan out per row, or whenever an agent is about to reach for SET VARIABLE, a macro, a loop, Python or a shell script to get around that wall. On dev: rows → statements → array_agg(http_post_form to /sql) → UNNEST, through the dev MCP sql tool or POST localhost:9495/sql. No macro. Other DuckDBs: quackapi in-process, the two-pipe form, or the quack loopback.
spatial	Answer questions about spatial data using DuckDB. Use when the user mentions locations, coordinates, lat/lng, distances, maps, addresses, "near", "within", "closest", geographic names, or spatial file formats (GeoJSON, Shapefile, GeoPackage, GPX, GeoParquet). Also triggers when the user wants to find places, buildings, or roads — Overture Maps provides free global data on S3 with zero API keys. Handles spatial joins, distance calculations, containment checks, density analysis, and format conversions for geographic data.
superhuman-docs	Read a Superhuman Docs (ex-Coda) document and land it on the dev quack as tables. Two independent doors: the Superhuman Docs MCP connector (OAuth, reads page prose AND tables) and the superhuman_docs DuckDB community extension (API token, ATTACH, tables only). Use when given a docs.superhuman.com or coda.io URL, when asked to read an InFrame HUB page, or when deciding which door a Superhuman doc should come through.
tera	The tera template engine inside DuckDB — tera_render(template, context JSON, autoescape :=) — as the one way this user's .sql files write text: generated .sql that is then .read, RESULTS.md assembled from COPY … (FORMAT markdown) tables, and self-contained HTML pages. Covers the two signatures, building the context (struct literal, to_json, list(t), json_group_object), the COPY-to-file form, the template syntax that works in this build and the parts that do not (no file loader, so no include/extends/import; no date, urlencode, slugify or filesizeformat; no //; filters bind looser than arithmetic; escape throws on non-strings), how to read and bisect its errors, and when minijinja is the better engine. Use when writing or debugging a tera_render call or a .tera template, when a .sql must generate another .sql, or when an agent is about to reach for a .sh, Python or string concatenation to produce text. The page recipe on top of this is /duckstack:live-page.
yaml	Read, inspect, validate, extract, convert, or write YAML with DuckDB's yaml extension. Reach for this when the source is .yaml/.yml, YAML frontmatter, an inline YAML value, or a remote description.yml that should become typed relational columns.

Install

From the local clone — the marketplace registers as duckdb-skills, the plugin is duckstack:

/plugin marketplace add ~/duckdb-skills
/plugin install duckstack@duckdb-skills

Codex reads the same manifest: codex plugin marketplace add ~/duckdb-skills && codex plugin add duckstack@duckdb-skills. Both CLIs cache by version: bump version in .claude-plugin/plugin.json and .claude-plugin/marketplace.json together, then claude plugin uninstall duckstack@duckdb-skills && claude plugin install duckstack@duckdb-skills (and codex plugin add duckstack@duckdb-skills again).