skardi-skills

Agent Skills for working with Skardi — a backend engine to provide SQL pipelines as http endpoints. These skills give your AI coding agent (Claude Code, Cursor, or any Agent Skills-compatible tool) deep knowledge of Skardi's patterns so you don't have to re-explain them each session.

Check out our demo here.

Available skills

Directory	Skill name	What it covers
skills/auto-context/	auto-context	Turn a folder of documents, a table you already have, or documents still inside a service into governed, searchable context an agent can query. Hybrid search (vector + full-text + RRF) served over HTTP by skardi-server. Three raw-material entries, one flow: a folder; an existing table (SQLite read directly and read-only, any other datastore piped in as NDJSON); or fetch-and-land — list, fetch each body, reconcile, ingest — where your agent writes the per-source fetch code and the skill fixes the process and its acceptance criteria. Storage is a separate choice: defaults to a local SQLite file the skill creates and owns (FTS5 + sqlite-vec vec0 mirrors kept in sync by triggers); point it at Postgres+pgvector, MongoDB, or Lance when the index should live in a database you already own. Handles prereq checks, model resolution, chunking and embedding inline in SQL, ingest, and retrieval end-to-end across candle / gguf / remote_embed. Never creates schema in a datastore you own — prints the SQL and waits — and never writes to a table given as raw material.
skills/retrieval/	retrieval	Answer questions from live data through a running skardi-server with the skardi CLI. Discovers sources, named pipelines, and the table schemas the deployment exposes, runs the question through any semantic search surface first (search-hybrid and friends), then writes read-only SQL against exact qualified table names, checks truncation before trusting counts, and reports with the query attached. Consumes whatever the server already has — it builds no index, writes no data, and starts no servers.
skills/graph-source/	graph-source	Connect a property graph (a knowledge graph, a GraphRAG corpus — Apache AGE / openCypher) to Skardi and query it through SQL, end to end: provision AGE with a least-privilege reader role, declare the type: graph source and its views in context YAML, triage registration health (healthy / degraded / refused, and what recovery does and does not answer), write correct queries (cypher_query, graph_schema, the JSON getters), and wire Cypher parameters into pipelines. Encodes the traps that bite in production: positional columns binding (same-typed columns declared out of RETURN order swap silently), no predicate pushdown into view Cypher (the bound lives in the view, RowCapExceeded otherwise), wrong-getter silently-NULL columns, the deliberately-absent ->/->> operators, lowercase-only view names, and the one working {params} pipeline spelling. Read-only by backend enforcement; AGE is the backend from Skardi v0.6.0 on (Neo4j/Kuzu are later milestones).
skills/graph-rag/	graph-rag	Answer questions whose evidence is in graph relationships: find or verify the named entities, traverse from them through read-only Cypher, and report the bounds and confidence of the edges used. Needs Skardi v0.6.0 or later, like graph-source.
skills/skardi-query-log/	skardi-query-log	Stop rewriting SQL you already got working. Every query goes through ask.py, which checks the index first: if this question has been asked, it hands back the statement that worked last time; if not, it files the one that works now. Reads the audit ledger skardi-server --query-audit-db writes (read-only) — seed_index.py picks unfiled queries out of it, read_failures.py reads the failures for what the system cannot answer, and read_log.py reports the overall shape, including whether the pipelines you built are being called. Turns a question into a real pipeline only when it keeps coming back, and then installs it itself: writes the YAML, restarts, checks /health and that /pipelines lists the new name, and rolls the file back out if the restart fails or the server comes back without it. The agent triggers this on its own; a user never asks for a log analysis.
skills/document-cache/	document-cache	When your agent is about to read a local PDF, DOCX, XLSX, PPTX, Markdown or text file, check whether Skardi already holds a parsed copy and, if so, read only the table of contents and the sections the question needs. Otherwise the agent reads the file locally and offers to upload it to your personal workspace — it never uploads without a decision recorded for that folder or an answer given this turn, and every failure falls back to the local read. Consent is remembered per folder in ~/.skardi/doc-cache.json. Needs the Skardi MCP tools (find_cached_document, prepare_document_upload, read_document) connected and a Skardi Cloud deployment with the document cache enabled; it does not query the cache with SQL or build any index.

A running skardi-server is required. Since Skardi's CLI became a thin HTTP client it holds no query engine and no local execution mode, so every path in auto-context starts a server, and retrieval connects to one that is already running. There is no CLI-only mode.

graph-source and graph-rag both require Skardi v0.6.0 or later. v0.5.0 has neither type: graph nor cypher_query, so neither skill can do anything against it. graph-source was verified against 1f2ecae, which v0.6.0 contains.

document-cache talks to Skardi Cloud, not to a local skardi-server. It needs the Skardi MCP tools connected and the document cache enabled on the deployment (it answers cache_unavailable otherwise, and the skill reads the local file). It uses nothing from the skardi CLI, so it is installed with any Skardi it is marked for; without the MCP tools it says once how to connect and reads files locally.

Each skill states the oldest Skardi it runs on, as metadata.skardi-min-version in its SKILL.md: a release number, or "main" while no release has what it needs. Skardi's install.sh reads it and skips a skill the installed skardi is too old for. A main build still reports the last release's version number, so a skill marked "main" is installed only when you pass --with-unreleased. A skill marked "main" also names what it waits for, as metadata.skardi-needs: an identifier that appears in the skardi source once the capability exists. CI looks for it in the latest Skardi release every day and fails once a release ships it, which is the signal to change "main" to that version; CI also rejects a SKILL.md without skardi-min-version.

skardi-query-log requires Skardi v0.6.0 or later, on a server you host yourself; Skardi Cloud is not supported yet. The audit ledger it reads is written by skardi-server --query-audit-db, which v0.6.0 is the first release to carry (git grep query_audit_db v0.5.0 is empty). What was measured against it, and what was not, is in the skill's own Verification section. auto-context and retrieval run on v0.5.0 too; only retrieval's --purpose / --session-id / --task flags need v0.6.0.

Installation

Claude Code (plugin marketplace, recommended)

From inside any Claude Code session:

/plugin marketplace add SkardiLabs/skardi-skills
/plugin install skardi@skardi-skills

That's it — all five skills are now available across all your projects, and /plugin marketplace update skardi-skills pulls future versions.

Changing a skill? Raise the version in the same PR. Claude Code compares only the plugin version when it looks for updates, so a skill merged without a new version never reaches anyone who already installed the plugin: claude plugin update skardi@skardi-skills reports it is already at the latest version. Run scripts/bump-version.sh <x.y.z> (minor for a new skill, patch for a fix); it sets every host manifest at once. CI fails a PR that changes skills/ or a manifest without a higher version than the base branch.

Upgrading from an earlier version: the individual plugins are now one, named skardi, so that every host can install this repository with its own one-line plugin command instead of a manual directory copy. Installed copies of the old per-skill plugins are not removed automatically — run /plugin uninstall auto-context, /plugin uninstall retrieval, /plugin uninstall graph-source and /plugin uninstall graph-rag, then install skardi. Further back: auto-knowledge-base and auto-rag were merged into auto-context; skardi-deploy-and-patterns and feishu-connector were retired, and Feishu cloud docs are now raw material for auto-context.

Claude Code (manual copy)

If you'd rather not use the plugin marketplace, copy the skill(s) into your personal skills directory so they're available across all projects:

# auto-context (searchable context over a folder or your own datastore)
cp -r skills/auto-context ~/.claude/skills/auto-context

# retrieval (answer questions from data a skardi-server already serves)
cp -r skills/retrieval ~/.claude/skills/retrieval

# graph-source (connect a property graph and query it through SQL)
cp -r skills/graph-source ~/.claude/skills/graph-source

# graph-rag (answer questions whose evidence is in graph relationships)
cp -r skills/graph-rag ~/.claude/skills/graph-rag

# skardi-query-log (stop rewriting SQL you already got working)
cp -r skills/skardi-query-log ~/.claude/skills/skardi-query-log
# document-cache (read cached documents by section instead of whole)
cp -r skills/document-cache ~/.claude/skills/document-cache

Claude Code will automatically load the relevant skill when your request matches it — e.g. "index these docs" / "make this folder searchable" / "build a RAG" / "expose hybrid search as HTTP" / "RAG service over our pgvector DB" for auto-context, or "query our database" / "how many orders last month" / "what tables do we have" for retrieval. You can also invoke them directly:

/auto-context
/retrieval
/document-cache

Other hosts, in one command

Two hosts install this repository directly through their own extension mechanism. Each reads its own manifest in this repo and picks up whatever is in skills/.

Gemini CLI — reads gemini-extension.json and discovers each skill by its location under skills/:

gemini extensions install https://github.com/SkardiLabs/skardi-skills

It asks twice: once to trust the current workspace, and once to accept a third-party extension after printing every skill it is about to install.

Pi — reads the pi.skills field in package.json:

pi install git:github.com/SkardiLabs/skardi-skills

How far these two have been checked: measured, on 2026-09-10. Both were installed from this repository and launched, and all four skills reached the agent in each. Gemini CLI 0.59.0 reports Extension "skardi" installed successfully and enabled, names all four under gemini extensions list, and loads them from ~/.gemini/extensions/skardi/skills/. Pi 0.75.5 shows the package with all four skills enabled in pi config and loads them from its clone of this repo. If a host rejects or silently ignores the plugin, please open an issue saying which host and version.

Kimi Code has no one-command path from this repository, and ships no manifest for one. Measured on Kimi Code CLI 1.50.0: kimi plugin install https://github.com/SkardiLabs/skardi-skills.git fails with No plugin.json at repository root, and a manifest put in a subdirectory for it to find is worse than none. It installs: kimi plugin list shows skardi v0.4.0 (installed) while no skill at all reaches the agent and the installed directory holds nothing but plugin.json. A Kimi plugin declares executable tools; a skills key is not part of that manifest and is ignored. Kimi Code discovers skills from directories only, and it reads ~/.agents/skills/, so use the checkout path below, which the next section already fills.

Codex, Cursor and Grok are also not in this list, because they distribute through their own reviewed marketplaces rather than from a repository manifest, and Hermes is not because a Hermes plugin has to register each skill from Python in __init__.py (skills/ is not auto-registered there) and would namespace them as skardi:auto-context. For all of them, and for any host below, use the checkout path.

Other Agent Skills hosts, from a checkout

Codex, Cursor, Pi, dsh, Kimi Code, OpenClaw and Hermes load these skills from a directory they resolve themselves; they differ in where that directory has to go. All of them install from a checkout:

git clone https://github.com/SkardiLabs/skardi-skills.git && cd skardi-skills

How far each of these has been checked. Two are measured. The ~/.agents/skills/ copy below was run for Kimi Code CLI 1.50.0 on 2026-09-10: all four skills reach the agent, under its User scope. The OpenClaw commands for auto-context and retrieval were run earlier: both install and the host lists them as ready. Everything else follows each host's own published skills documentation and has not been installed and launched by us. Those are the documented paths, not measured ones — if one of them does not pick the skill up, please open an issue and say which host and version, since that is the kind of thing only a user on that host can catch.

Codex, Cursor, Pi, dsh, Kimi Code

All five read the cross-tool ~/.agents/skills/ convention, so one copy covers every one of them:

mkdir -p ~/.agents/skills
cp -r skills/auto-context ~/.agents/skills/auto-context
cp -r skills/retrieval ~/.agents/skills/retrieval
cp -r skills/graph-source ~/.agents/skills/graph-source
cp -r skills/graph-rag ~/.agents/skills/graph-rag
cp -r skills/skardi-query-log ~/.agents/skills/skardi-query-log
cp -r skills/document-cache ~/.agents/skills/document-cache

To scope the skill to a single project instead, copy it into that repo's .agents/skills/. Each host also keeps a native directory if you'd rather install per tool — ~/.cursor/skills/ for Cursor, ~/.pi/agent/skills/ for Pi, ~/.dsh/skills/ for dsh, ~/.kimi/skills/ for Kimi Code — while Codex uses ~/.agents/skills/ as its only personal location.

OpenClaw

OpenClaw installs from a local path through its own CLI rather than by copying:

openclaw skills install ./skills/auto-context
openclaw skills install ./skills/retrieval
openclaw skills install ./skills/graph-source
openclaw skills install ./skills/graph-rag
openclaw skills install ./skills/skardi-query-log
openclaw skills install ./skills/document-cache

That installs into ~/.openclaw/workspace/skills/, scoped to the active agent workspace. Add --global to install into ~/.openclaw/skills/ instead, which every local agent sees.

Hermes

Hermes treats ~/.hermes/skills/ as its source of truth:

mkdir -p ~/.hermes/skills
cp -r skills/auto-context ~/.hermes/skills/auto-context
cp -r skills/retrieval ~/.hermes/skills/retrieval
cp -r skills/graph-source ~/.hermes/skills/graph-source
cp -r skills/graph-rag ~/.hermes/skills/graph-rag
cp -r skills/skardi-query-log ~/.hermes/skills/skardi-query-log
cp -r skills/document-cache ~/.hermes/skills/document-cache

Hermes does not scan ~/.agents/skills/ as a personal directory — inside a git repo it reads <repo>/.hermes/skills/ and <repo>/.agents/skills/. To share one personal folder with the hosts above, add it under skills.external_dirs in ~/.hermes/config.yaml.

Anything else

If your host isn't listed, put the skill directory wherever it resolves personal or project skills and restart it. These files follow the Agent Skills open standard, but conforming to the format does not guarantee a host will load them — hosts add rules of their own. auto-context is named in kebab-case for that reason: dsh rejects any other shape outright, and OpenClaw derives its install slug from the same field.

Do not read a successful install elsewhere as proof that a name is fine. Gemini CLI 0.59.0, Kimi Code CLI 1.50.0 and Pi 0.75.5 enforce nothing here. Measured with probe skills on 2026-09-10: a SKILL.md whose name: uses underscores, and one whose name: disagrees with its own directory, both load on all three, and gemini extensions validate passes them too. On all three the name the agent sees comes from the name: field rather than from the directory, so the two can drift apart with nothing to show for it. That is the failure dsh and OpenClaw catch and these hosts do not, which is why every skill here keeps name: in kebab-case and identical to its directory name, and why CI asserts both on every pull request rather than trusting an install to complain.

Bundled resources per skill

skills/auto-context/

Executable scripts, per-backend YAML templates, and reference docs the skill invokes:

Path	Purpose
scripts/setup_context.py	Renders the workspace — resolves the embedding choice (model path / provider args / dim), renders ctx.yaml + semantics.yaml + the five pipeline YAMLs for the chosen backend, and records a breadcrumb (.embedding.txt) the later scripts read. Defaults to --backend sqlite, where it owns the .db inside the workspace; --backend postgres requires a connection string and table the user created
scripts/start_server.py	Starts skardi-server in one of three runtimes (local-process / docker / kubernetes), polls /health, verifies the five pipelines are registered, writes server.runtime + server.port for follow-up scripts. Server startup is the connectivity check — it fails naming the source it could not open
scripts/stop_server.py	Tears down whichever runtime was launched (kills the local pid, removes the docker container, or kubectl deletes the rendered manifests)
scripts/ingest_corpus.py	Walks a corpus directory and POSTs one document per request to /ingest-chunked/execute. Chunking (chunk()) and embedding both happen inline in server-side SQL, so a document lands completely or not at all. Progress is journalled, so a re-run resumes instead of duplicating
assets/sqlite/, assets/postgres/	Per-backend ctx.yaml + semantics.yaml + pipelines/*.yaml templates. Same five pipeline names on both sides (ingest, ingest_chunked, search_vector, search_fulltext, search_hybrid), so only the backend-specific lines differ. Mongo and Lance trees follow the same layout when added
references/schemas.md	The exact DDL the user must run themselves per backend (Postgres+pgvector, MongoDB index commands, Lance dataset bootstrap)
references/runtimes.md	Per-runtime walk-through (mounts, networking, lifecycle, kubectl flags, port-forward, cleanup)
references/pipeline_patterns.md	The exact SQL the skill generates, with commentary on RRF, the DataFusion INSERT-VALUES quirk, and how to extend the pipelines (metadata filters, updates, deletes)

skills/document-cache/

Path	Purpose
scripts/doc_cache.py	Python standard library only, no token. check <path> hashes the file and reports its content type, size, the folder consent applies to (the git root, otherwise the file's folder) and the recorded decision, whether git ignores it and whether "always" may be offered; consent <path> always|never records a decision for that folder and its subfolders ("always" is refused for the home folder and /); upload <path> [--once] streams a single-use ticket PUT (the ticket URL is read from stdin, never argv; it refuses a never folder, a missing consent without --once, a non-https or non-ticket URL, an unsupported type and any file git ignores); record <path> <sha256> notes which hash was last uploaded for the path. State is ~/.skardi/doc-cache.json ($SKARDI_HOME overrides the directory), written atomically with mode 0600. Absolute paths never leave the machine
evals/evals.json	Seven execution cases (first read asks, an always folder, a never folder, a parsed hit read by section, a changed file sends replaces, a gitignored file never uploads, a home-folder file offers no "always") and three trigger cases (including that reading a README while coding does not trigger)

skills/retrieval/

No scripts — the skill is the procedure: SKILL.md is the whole skill.

skills/skardi-query-log/

Path	Purpose
scripts/ask.py	The path every query takes. Without --sql it lists what has been asked and any pitfalls filed from past failures; with --sql it runs the statement and files it in the index on success. The index holds one row per question, not per query, so it grows with distinct questions rather than with usage. Keeps the index out of the skill directory, because it holds real queries and real field names. An index belongs to one server: when the skardi CLI is pointed at a different one, it stops (exit 3) instead of answering from the wrong server's SQL
scripts/seed_index.py	Lists the succeeded queries in the ledger that carry a stated purpose but never reached the index — queries sent around ask.py are not lost, just unfiled — and files the ids you pass to --keep. The rest of that batch is recorded as unwanted so you are not asked twice. Picking is yours: the log mixes test runs with real work and the script cannot tell them apart
scripts/read_failures.py	Groups failures by the wording Skardi itself emits — missing table, missing field, action not allowed, runtime breakage, wrong call form — and flags the ones where the same table was queried successfully afterwards. With --index, pairs each failure with the statement that later worked and files it as a pitfall, with both statements kept exactly as they ran, so step one of ask.py shows it before the next query. Failures need no volume: one row carries information
scripts/read_log.py	Opens the audit ledger read-only and formats rows — an overview (totals, pass/fail, sessions), the last N statements, one session, failures only. Reads statement_kind = 'query' by default so a pipeline run cannot be counted as another instance of the question it already answers; --kind pipeline asks the opposite question, whether a pipeline you built is being called. Matched case-insensitively, because the column is case-sensitive and its casing changed under existing ledgers (skardi#219) — matching = 'query' on an older one returns zero rows and says nothing. Makes no judgements: which repeats deserve hardening is the agent's call
scripts/add_pipeline.py	Installs one pipeline and verifies its own work — writes the YAML, runs the restart command you supply, polls /health and checks that /pipelines lists the new name, and when the restart command fails or the pipeline is not there, deletes the file and restarts again so the server is left as it was found. , and are required and never guessed: one pipeline that fails to plan takes the whole server down at startup