claude godot docs and ast grep skills

claude/.claude/skills/gdscript-ast-grep/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gdscript-ast-grep
+description: Use when running ast-grep against GDScript (.gd) files — pattern-writing quirks specific to the tree-sitter-gdscript grammar (registered as language `gdscript` via the custom-language sgconfig). Covers why `$$$` (multi-metavariable) patterns silently fail to match, how to write working `func` search patterns, and other known-weak GDScript patterns. Pair with the general `ast-grep` skill for retry/fallback mechanics.
+---
+
+# ast-grep on GDScript
+
+`gdscript` is a custom grammar (not built into ast-grep), registered in `sgconfig.yml`. It's discovered automatically — omit `-l` and let extension auto-detection pick it up, or pass `-l gdscript` explicitly (never `-l gd`, that's the extension, not the language name).
+
+## Searching for functions
+
+Don't end a `func` pattern in a bare `:` — with or without a `$$$` body, it won't match:
+
+```
+func $NAME($$$) -> $RET:        # ✗ never matches (trailing colon, no body)
+func $NAME($$$) -> $RET:
+	$$$BODY                     # ✗ never matches ($$$ body collides with $)
+```
+
+Instead, match just the header and drop the trailing colon/body entirely — ast-grep still returns the whole function node, body included:
+
+```
+func $NAME($$$)                 # ✓ matches the full function, header through body
+func $NAME($$$) -> $RET         # ✓ same, if you need the return type bound
+```
+
+GDScript also has `static func` — if a plain `func $NAME($$$)` pattern doesn't hit a function you know exists, retry with `static func $NAME($$$)` before falling back to rg.
+
+## Other known-weak patterns
+
+These don't match even though they look valid — prefer a literal/simpler pattern or fall back to rg per the usual rule:
+
+- Typed declarations: `const $N := $V`, `var $N := $V`
+- Chained/dotted method calls: `$O.$M()`, `$X.connect($Y)` — tree-sitter-gdscript parses chains like `a().b().c.connect(d)` as one flat `attribute` node, not a nested chain, so these never bind.
+- Bare-colon fragments other than `func`: `if $C:`, `for $V in $C:` — same trailing-colon/body issue as above.
+
+Literal calls (`_clear_hover()`), bare identifiers, and `return $X`-style single-metavariable patterns all match reliably.
+
+## Why: the `$` collision
+
+Root cause behind most of the above: GDScript's `$` is a real operator (`$Sprite` / `$"../Path"` is shorthand for `get_node(...)`), and ast-grep also uses `$` for metavariables (`$X`) and `$$$` for "match zero-or-more". Single metavariables happen to parse fine, but `$$$` immediately followed by an identifier (e.g. `$$$BODY`) produces a stray `ERROR` node instead of a clean placeholder, so the whole pattern fails to compile — silently, with no error text. This is an inherent sigil clash, not a bug to chase; see the general `ast-grep` skill for what to do when a pattern fails (retry simpler, then fall back to rg).

claude/.claude/skills/godot-docs/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: godot-docs
+description: Use whenever you need Godot Engine API facts — a class, method signature, property, signal, constant, enum, annotation or theme item — or when you are unsure whether a Godot symbol exists. Run the offline `godoc` CLI instead of guessing from memory or fetching docs.godotengine.org, because `godoc` is indexed from the exact engine source this machine builds against.
+---
+
+# Godot API reference (offline)
+
+`godoc` serves the Godot class reference from a local SQLite index built out of
+the engine source tree. It is authoritative for the installed engine version.
+Check the version with `godoc info`.
+
+**Do not answer Godot API questions from memory.** Signatures change between
+minor versions. Run the tool.
+
+**Do not fetch docs.godotengine.org** for class reference. The website tracks a
+different version than the local build.
+
+## Commands
+
+```bash
+godoc show Node3D                 # full class: description, members, subclasses
+godoc show Node3D --brief         # header and member counts only
+godoc show Node3D.look_at         # one member, with parameters and defaults
+godoc show Sprite2D.position      # resolves through the inheritance chain
+godoc look_at                     # bare name: every class that declares it
+godoc search rotate toward point  # full text search, bm25 ranked
+godoc members Button --kind signal
+godoc tree CharacterBody2D
+godoc info                        # engine version and index build time
+```
+
+Add `--json` to any command for structured output.
+Add `--kind`, `--cls`, `-n` to `search`. Run `godoc kinds` for valid kinds.
+
+## Which command to use
+
+| You need | Command |
+|---|---|
+| An exact signature you can name | `godoc show Class.member` |
+| To know what a class offers | `godoc show Class` |
+| Only one category of member | `godoc members Class --kind method` |
+| To find a symbol by behaviour | `godoc search <words>` |
+| To confirm a symbol exists | `godoc show <name>`, exit 1 means no |
+
+Use `show` before `search`. Exact lookup is precise; search is ranked prose
+matching and can rank a near miss first.
+
+## Exit codes
+
+`0` hit, `1` no match, `2` index missing or unreadable.
+On exit 2, run `godoc index --force`.
+
+## Scope
+
+Covers the class reference only: 1058 classes, ~23.7k members, including
+`@GDScript` annotations and `@GlobalScope` functions. It does **not** cover the
+narrative tutorials (2D/3D guides, shader guides, export guides). Use WebFetch
+on docs.godotengine.org for those, and say so when you do.
+
+## Maintenance
+
+Source: `~/projects/godoc` (stdlib Python only, no virtualenv).
+After a `git pull` in the Godot source, run `godoc index --force`.
+See `~/projects/godoc/README.md` to change or extend the tool.
+
+The same index is available over MCP for Claude Desktop and Cursor. Run
+`godoc mcp --install` to register it, or `godoc mcp --print-config` for the
+snippet. In Claude Code, prefer the CLI above: it costs no context until you
+call it.
+
+To set the tool up on another machine, follow
+`~/projects/godoc/INSTALL-MCP.md`. It is a runbook written for an agent and it
+covers fetching the Godot documentation XML.