Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add posit-dev/ggsql-python

Works with Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex, and 30+ other agents.

Codex / OpenCode — tell the agent:

Fetch the skill file from https://github.com/posit-dev/ggsql-python and follow the instructions.

Manual — download the skill file:

curl -O <site-url>/skill.md

Or browse the SKILL.md file.

SKILL.md

---
name: ggsql
description: >
  SQL extension for declarative data visualization. Use when writing Python code that uses the ggsql package.
license: MIT
compatibility: Requires Python >=3.10.
---

# ggsql

SQL extension for declarative data visualization

## Installation

```bash
pip install ggsql
```

## API overview

### High-level API

Convenience entry points for common workflows.

- `render_altair`: Render a DataFrame with a VISUALISE spec to an Altair chart
- `validate`: Validate query syntax and semantics without executing SQL
- `execute`: Execute a ggsql query using a custom Python reader

### Readers

Execute SQL and manage DataFrames that feed visualizations.

- `DuckDBReader`: DuckDB database reader for executing SQL queries

### Writers

Turn a resolved Spec into rendered output.

- `VegaLiteWriter`: Vega-Lite v6 JSON output writer

### Result types

Objects returned from `validate()` and `reader.execute()`.

- `Validated`: Result of validate() - query inspection and validation without SQL execution
- `Spec`: Result of reader.execute(), ready for rendering

### Validated Methods

Methods for the Validated class

- `Validated.errors`
- `Validated.has_visual`
- `Validated.sql`
- `Validated.valid`
- `Validated.visual`
- `Validated.warnings`

### Spec Methods

Methods for the Spec class

- `Spec.data`
- `Spec.layer_count`
- `Spec.layer_data`
- `Spec.layer_sql`
- `Spec.metadata`
- `Spec.sql`
- `Spec.stat_data`
- `Spec.stat_sql`
- `Spec.visual`
- `Spec.warnings`

## Resources

- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/posit-dev/ggsql-python)