thedivergentai/GD-Agentic-Skills

GD Agentic Skills – Godot 4 Mastery Ecosystem

What it is

• A curated collection of 99 “Domain Skills” (formerly micro‑skills) that encode best‑practice Godot 4.7+ code, architecture patterns, and production‑ready GDScript snippets.
• The library is designed as an external long‑term memory for AI coding agents (e.g., Claude Code, Cursor, Gemini‑CLI, etc.).
• One special skill, godot‑master, acts as an orchestrator that references all other skills and adds decision‑matrices, anti‑patterns, and performance budgets.

Why it matters

• Modern AI agents often “hallucinate” or produce code that drifts from the official Godot documentation.
• By feeding agents a deterministic, token‑compact knowledge base, the project aims to keep the model’s context focused and its output aligned with the engine’s current APIs.
• The repo also ships a vision skill (godot‑agent‑vision) that lets agents capture editor GUI/asset screenshots, convert them to WebP, and score the result against a production rubric—giving agents a way to see the project rather than just read file paths.

---

Core Concepts

Concept	What it does
Domain Skills	Small, self‑contained markdown files (SKILL.md) that describe a single Godot feature (e.g., godot‑characterbody‑2d, godot‑game‑loop‑waves). Each includes reference links to the official docs, sample scripts, and migration notes.
Godot‑master	A “lead architect” skill that aggregates all 99 domain skills, adds a decision‑matrix, anti‑pattern list, performance budgets, and a layered signal‑based architecture diagram. It is the go‑to entry point for new projects or for agents that need full‑project guidance.
Agent‑First Design (DIA Loop)	The Discovery‑Ingestion‑Application loop tells agents how to locate the skills_index.json, read the appropriate SKILL.md files, and apply the knowledge without over‑loading the model’s context.
Installation Rubric	A table of per‑agent install flags (-a cursor, -a claude-code, …) and the expected directory layout (.agents/skills/, ~/.cursor/skills/, etc.).
Context‑Storm Guardrails	Explicit warnings not to use --all when installing; installing every skill at once would consume ~15 k tokens and cause “metadata flood” that slows reasoning.

---

Quick‑Start Paths

Path	When to use	Command (via the skills CLI)
A – The Architect	Starting a brand‑new project or need a full audit of an existing project.	npx skills add thedivergentai/gd-agentic-skills/skills/godot-master -g -a <agent> -y
B – The Specialist	Only need a single feature (e.g., 2‑D movement, inventory).	npx skills add thedivergentai/gd-agentic-skills/skills/godot-characterbody-2d -g -a <agent> -y

After installing, run npx skills list -g -a <agent> to verify and restart the host agent so it loads the new skill files.

---

Notable Updates (latest v0.0.11)

• godot‑agent‑vision – captures editor GUI/asset viewports, stores them as WebP, and scores the visual output against a granular rubric (typography‑weighted, anti‑slop, identity).
• Cross‑platform host CLI – a thin wrapper (Win/macOS/Linux) that bridges the repository to the agent; it lives under .gdskills/ and is not an in‑game Autoload.
• Migration Station – a dedicated skill (godot‑version‑migration) that guides agents through step‑by‑step upgrades from any older Godot version up to 4.7, with per‑skill migration notes.
• Reference Lattice – every domain skill now ends with a curated list of official Godot docs and related skills, enabling agents to “research deeper” without leaving the skill graph.

---

Intended Audience

• AI coding agents that generate or refactor Godot projects (Claude Code, Cursor, Gemini‑CLI, etc.).
• Human developers who want a token‑efficient, vetted reference library to feed into their own agents or to browse manually.
• Educators / mentors looking for a structured, up‑to‑date set of Godot best‑practice examples that can be programmatically queried.

---

Limitations & Caveats

• The library is external to Godot; it does not install as a Godot plugin or Autoload. Agents must read the markdown files and inject the supplied snippets themselves.
• It relies on the skills CLI (the Vercel‑Labs tool) for installation. Users not using that CLI will need to follow the “Clone / DIA path” workflow: read skills_index.json and open the relevant SKILL.md files with the agent’s file‑tool.
• Installing all 99 skills at once is discouraged because it consumes a large token budget and can cause “Context Storms.” The recommended pattern is either the single godot‑master orchestrator or a handful of targeted domain skills.
• The vision skill currently outputs budgeted WebP images and a rubric score; it does not perform full‑fledged image analysis beyond the provided rubric.

---

Bottom Line

GD Agentic Skills is a purpose‑built, token‑efficient knowledge base that lets AI coding agents work with Godot 4.7+ in a disciplined, best‑practice‑first manner. By installing either the all‑encompassing godot‑master skill or selective domain skills, agents gain access to curated documentation links, production‑grade GDScript snippets, migration guidance, and even visual verification—all without overwhelming the model’s context.

---

Quick reference links

• Full skill index: skills_index.json
• Godot‑master skill: skills/godot-master/SKILL.md
• Vision skill: skills/godot-agent-vision/SKILL.md
• Installation guide: see the ⚡ Quick Start table above.