From b8e67652a64aa40216fb580f2878f62357138881 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 12 Jun 2026 14:42:05 +0200 Subject: [PATCH 1/5] alias skill cli command --- doc/get_started/tooling/cli.qmd | 2 +- ggsql-cli/CLAUDE.md | 1 + ggsql-cli/src/main.rs | 10 +++++++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/get_started/tooling/cli.qmd b/doc/get_started/tooling/cli.qmd index f3a99e158..78a0edb1b 100644 --- a/doc/get_started/tooling/cli.qmd +++ b/doc/get_started/tooling/cli.qmd @@ -76,7 +76,7 @@ visualisation. A layer is a single instance of a visual representation of a data [...] ``` -A ggsql skill, a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command. +A ggsql skill, a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command (also available as `ggsql agent-info`). ```bash $ ggsql skill diff --git a/ggsql-cli/CLAUDE.md b/ggsql-cli/CLAUDE.md index d7e51b9c5..c6ed59703 100644 --- a/ggsql-cli/CLAUDE.md +++ b/ggsql-cli/CLAUDE.md @@ -28,6 +28,7 @@ The binary name is `ggsql` (not `ggsql-cli`) — that's what release artifacts a | `validate` | Syntax + semantic check without executing SQL | | `docs` | Render embedded ggsql syntax docs (TTY → ANSI via termimad, pipe → markdown, `--format json` → structured) | | `skill` | Render the AI-assistant skill from `/doc/vendor/SKILL.md` | +| `agent-info` | Alias for `skill` | Only public `ggsql::*` API is used (`reader`, `writer`, `validate`, `parser`, `VERSION`) — this crate has no awareness of internal modules. diff --git a/ggsql-cli/src/main.rs b/ggsql-cli/src/main.rs index f6348d8a7..d1b0cb0de 100644 --- a/ggsql-cli/src/main.rs +++ b/ggsql-cli/src/main.rs @@ -120,6 +120,14 @@ pub enum Commands { #[arg(long, value_enum)] format: Option, }, + + /// Alias for `skill` — show the ggsql usage guide for AI assistants + #[command(name = "agent-info")] + AgentInfo { + /// Output format. Defaults to rendered text on a TTY, raw markdown when piped. + #[arg(long, value_enum)] + format: Option, + }, } #[derive(ValueEnum, Clone, Copy, Debug, PartialEq, Eq)] @@ -178,7 +186,7 @@ fn main() -> anyhow::Result<()> { cmd_docs(first, second, format); } - Commands::Skill { format } => { + Commands::Skill { format } | Commands::AgentInfo { format } => { cmd_skill(format); } } From 1139fac71ddd872ba3859424d1e24558d5a37cb3 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 12 Jun 2026 17:26:10 +0200 Subject: [PATCH 2/5] add skill page --- doc/_quarto.yml | 2 ++ doc/syntax/skill.qmd | 15 +++++++++++++++ 2 files changed, 17 insertions(+) create mode 100644 doc/syntax/skill.qmd diff --git a/doc/_quarto.yml b/doc/_quarto.yml index 880752e1d..e19046fe8 100644 --- a/doc/_quarto.yml +++ b/doc/_quarto.yml @@ -125,6 +125,8 @@ website: - section: Coordinate systems contents: - auto: syntax/coord/* + - text: Agent Skill + href: syntax/skill.qmd - id: get_started title: Get started style: "floating" diff --git a/doc/syntax/skill.qmd b/doc/syntax/skill.qmd new file mode 100644 index 000000000..b7174aa0b --- /dev/null +++ b/doc/syntax/skill.qmd @@ -0,0 +1,15 @@ +--- +title: "Skill" +description: "A complete ggsql syntax reference designed for AI coding assistants and humans alike." +title-block-style: none +--- + +The ggsql skill is a self-contained reference designed for AI coding assistants. It documents the full query syntax in a compact format that can be consumed by LLMs or read by humans as a quick-reference. + +The same content is available via the CLI with `ggsql skill`, or can be installed as an [AI skill](https://github.com/posit-dev/skills) with `npx skills add posit-dev/skills --skill ggsql`. + +[Raw source](https://github.com/posit-dev/skills/blob/main/skills/ggsql/SKILL.md) + +--- + +{{< include ../vendor/SKILL.md >}} From 23046b5bad774e9d98a35f0d0fc8b9293175b178 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 12 Jun 2026 17:28:10 +0200 Subject: [PATCH 3/5] add faq section --- doc/faq.qmd | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/faq.qmd b/doc/faq.qmd index 275266ee1..3a3dbb8ad 100644 --- a/doc/faq.qmd +++ b/doc/faq.qmd @@ -101,6 +101,22 @@ ggsql integrates very deeply with the database backends and handles all statisti ggsql does not yet support interactive functionality like tool tips and zooming. This is a point of focus for us and we will rather get the syntax and implementation right than rush to it. ::: +## AI assistance + +::: {.callout-note collapse="true"} +## How do I get my AI assistant to write ggsql? + +We maintain a [skill](syntax/skill.qmd) — a compact syntax reference designed for LLMs. You can install it with: + +```sh +npx skills add posit-dev/skills --skill ggsql +``` + +This works with any AI coding assistant that supports the [skills](https://github.com/posit-dev/skills) framework. Once installed, your assistant can write and modify ggsql queries using the full syntax. + +Alternatively, the same reference is available via `ggsql skill` on the command line. +::: + ## Troubleshooting ::: {.callout-note collapse="true"} From 8226674f09e537eb52e3cb122dcf50ab00bf6f28 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 12 Jun 2026 17:32:25 +0200 Subject: [PATCH 4/5] another link --- doc/get_started/tooling/cli.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/get_started/tooling/cli.qmd b/doc/get_started/tooling/cli.qmd index 78a0edb1b..dc7a484ac 100644 --- a/doc/get_started/tooling/cli.qmd +++ b/doc/get_started/tooling/cli.qmd @@ -76,7 +76,7 @@ visualisation. A layer is a single instance of a visual representation of a data [...] ``` -A ggsql skill, a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command (also available as `ggsql agent-info`). +A ggsql [skill](../../syntax/skill.qmd), a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command (also available as `ggsql agent-info`). ```bash $ ggsql skill From cb3b486c3fb65fd8971ee02a7066b836f5618422 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 12 Jun 2026 17:40:18 +0200 Subject: [PATCH 5/5] fix link --- doc/syntax/skill.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/syntax/skill.qmd b/doc/syntax/skill.qmd index b7174aa0b..ffc0c193e 100644 --- a/doc/syntax/skill.qmd +++ b/doc/syntax/skill.qmd @@ -8,7 +8,7 @@ The ggsql skill is a self-contained reference designed for AI coding assistants. The same content is available via the CLI with `ggsql skill`, or can be installed as an [AI skill](https://github.com/posit-dev/skills) with `npx skills add posit-dev/skills --skill ggsql`. -[Raw source](https://github.com/posit-dev/skills/blob/main/skills/ggsql/SKILL.md) +[Raw source](https://github.com/posit-dev/skills/blob/main/ggsql/ggsql/SKILL.md) ---