Improvements around skill.md

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"

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"}

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](../../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

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/ggsql/ggsql/SKILL.md)
+
+---
+
+{{< include ../vendor/SKILL.md >}}

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.
 

ggsql-cli/src/main.rs

@@ -120,6 +120,14 @@ pub enum Commands {
         #[arg(long, value_enum)]
         format: Option<DocsFormat>,
     },
+
+    /// 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<DocsFormat>,
+    },
 }
 
 #[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);
         }
     }