Provide a Grats skill to our users

llm-docs/getting-started/quick-start.md

@@ -14,6 +14,13 @@ npm init --yes && npm pkg set type="module"
 
 ## Install dependencies
 
+> **TIP:**
+> If you use an AI coding agent, install the Grats skill to make it a Grats expert:
+> 
+> ```bash
+> npx skills add captbaritone/grats
+> ```
+
 Grats can be used with many different GraphQL servers, but this example uses `graphql-yoga`.
 
 ```bash

skills/grats/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: grats
+description: Build GraphQL servers by annotating TypeScript code with docblock tags like @gqlType and @gqlField. Use when writing, reviewing, or refactoring GraphQL resolvers in a project that uses Grats, or when the user mentions Grats, @gqlType, @gqlField, or similar docblock tags.
+license: MIT
+metadata:
+  author: grats
+  version: "1.0.0"
+---
+
+# Grats
+
+Grats extracts a GraphQL schema from TypeScript code. Instead of writing a separate schema file, you annotate your TypeScript types and functions with docblock tags like `/** @gqlType */` and `/** @gqlField */`. Grats then generates an executable GraphQL schema and a `.graphql` file as a build step.
+
+## Documentation
+
+Grats ships comprehensive documentation in its npm package at `node_modules/grats/llm-docs/`. Read these files for detailed reference:
+
+- **Getting started**: `node_modules/grats/llm-docs/getting-started/quick-start.md`
+- **All docblock tags**: `node_modules/grats/llm-docs/docblock-tags.md`
+- **Resolver patterns**: `node_modules/grats/llm-docs/resolvers.md`
+- **Configuration**: `node_modules/grats/llm-docs/getting-started/configuration.md`
+- **CLI usage**: `node_modules/grats/llm-docs/getting-started/cli.md`
+
+## How to Write Grats Code
+
+Write idiomatic TypeScript — classes, type aliases, interfaces, functions — whatever style suits the project. Then add docblock tags (`/** @gqlType */`, `/** @gqlField */`, etc.) to the constructs you want to expose in the GraphQL schema. Grats infers the GraphQL meaning from your TypeScript types. If something is ambiguous or incorrect, Grats will give you a helpful error message telling you how to fix it.
+
+You do not need to learn a specific pattern or DSL. Just write the TypeScript code that feels natural and annotate it. Grats supports classes, interfaces, type aliases, functions, static methods, and more — use whatever fits.
+
+Annotate the project's existing model types and data classes directly rather than creating a separate "resolver" layer with new wrapper types. Grats is designed to work with your real domain types — add `@gqlType` and `@gqlField` to the types you already have.
+
+### Docblock Tags
+
+Each tag maps directly to a GraphQL schema construct. Tags must use `/**` (two asterisks).
+
+| Tag                     | Purpose                                        |
+| ----------------------- | ---------------------------------------------- |
+| `@gqlType`              | Define a GraphQL object type                   |
+| `@gqlField`             | Define a field on a type                       |
+| `@gqlQueryField`        | Define a field on the root `Query` type        |
+| `@gqlMutationField`     | Define a field on the root `Mutation` type     |
+| `@gqlSubscriptionField` | Define a field on the root `Subscription` type |
+| `@gqlInterface`         | Define a GraphQL interface                     |
+| `@gqlUnion`             | Define a GraphQL union                         |
+| `@gqlEnum`              | Define a GraphQL enum                          |
+| `@gqlScalar`            | Define a custom GraphQL scalar                 |
+| `@gqlInput`             | Define a GraphQL input type                    |
+| `@gqlContext`           | Mark a type as the GraphQL context object      |
+
+For detailed documentation on each tag, read the files in `node_modules/grats/llm-docs/docblock-tags/`.
+
+### Configuration
+
+Grats is configured under the `"grats"` key in `tsconfig.json`:
+
+```json
+{
+  "grats": {
+    "nullableByDefault": true,
+    "importModuleSpecifierEnding": ".js"
+  }
+}
+```
+
+For all options, read `node_modules/grats/llm-docs/getting-started/configuration.md`.
+
+### Running Grats
+
+```bash
+npx grats          # Generate schema
+npx grats --watch  # Watch mode
+npx grats --fix    # Auto-fix common issues
+```
+
+Rerun Grats after any change that is expected to modify the GraphQL schema (adding or changing types, fields, arguments, etc.) to regenerate the schema files.
+
+The project may have its own script or workflow for running Grats (e.g., an npm script, a build step, or a watch task). Check the project's `package.json` scripts and documentation first, and defer to the project's approach if one exists.
+
+### Working with Generated Files
+
+Grats generates `schema.ts` and `schema.graphql`. These files should be **committed to the repository** — they are expected to be checked in so that schema changes are visible in code review and accessible to other tools. Do not add them to `.gitignore`.
+
+Do not manually edit generated files or run autoformatters on them. If CI fails with a "schema out of date" error, rerun Grats and commit the updated files.
+
+For more details, read `node_modules/grats/llm-docs/guides/workflows.md`.
+
+## Things You Might Not Expect
+
+- **All fields are nullable by default** per GraphQL best practices — `string` produces `String`, not `String!`. Prefer keeping fields nullable. `@killsParentOnException` can make a field non-null, but use it with caution: if the resolver throws, the error propagates up and nulls out the nearest nullable parent, increasing the blast radius. For projects that want clients to see which fields are _expected_ to be non-null absent errors, enable `strictSemanticNullability` in the Grats config. See `node_modules/grats/llm-docs/resolvers/nullability.md` and `node_modules/grats/llm-docs/guides/strict-semantic-nullability.md`.
+- **Root types are auto-created.** `@gqlQueryField` automatically creates the `Query` type — you don't need to define it separately. See `node_modules/grats/llm-docs/docblock-tags/root-fields.md`.
+- **`@deprecated` JSDoc tag auto-maps** to the GraphQL `@deprecated` directive. No need for `@gqlAnnotate`. See `node_modules/grats/llm-docs/resolvers/deprecated.md`.
+- **Generics are supported.** `Connection<User>` auto-materializes as `UserConnection` in the schema. See `node_modules/grats/llm-docs/guides/generics.md`.
+- **Derived context values** enable dependency injection: a function annotated with `@gqlContext` that takes the root context and returns a new type creates an injectable value. See `node_modules/grats/llm-docs/docblock-tags/context.md`.
+
+## Additional Documentation
+
+For advanced topics, read the files in `node_modules/grats/llm-docs/`:
+
+- **Guides**: `guides/` — subscriptions, dataloader, generics, incremental migration, workflows, permissions, connection spec
+- **FAQ**: `faq/` — design principles, limitations, how Grats works
+- **Examples**: `examples/` — Apollo Server, Yoga, Next.js, production app patterns

website/docs/01-getting-started/01-quick-start.mdx

@@ -14,6 +14,15 @@ npm init --yes && npm pkg set type="module"
 
 ## Install dependencies
 
+:::tip
+If you use an AI coding agent, install the Grats skill to make it a Grats expert:
+
+```bash
+npx skills add captbaritone/grats
+```
+
+:::
+
 Grats can be used with many different GraphQL servers, but this example uses `graphql-yoga`.
 
 ```bash