Agent Skills

godot-mechanic-secrets

The official "Long-Term Memory" for Godot 4 AI Agents. A high-density library of 82+ expert skills and 26 genre blueprints, providing deterministic, strictly typed GDScript patterns optimized for recursive machine discovery and production-grade game engineering.

Instalación
CLI
npx skills add https://github.com/thedivergentai/gd-agentic-skills --skill godot-mechanic-secrets

Instala esta habilidad con la CLI y comienza a usar el flujo de trabajo SKILL.md en tu espacio de trabajo.

Última actualización 4/22/2026

GD Agentic Skills: The Godot 4 Mastery Ecosystem

GD Agentic Skills - Godot 4.x Mastery Library

GitHub Stars
License
Godot Version
Skills
Last Commit

"A skill forgotten is a power lost." — The Code Architect

Brought to you by Divergent AI

💬 A Message from the Creator (Divergent AI)

March 19, 2026

Hey everyone, Divergent AI here! I'm super happy that I'm seeing the project getting some love. It's motivated me to come back at it with a really strong update for you all. I've spent many hours working on updating all microskills to be completely packed with top expert-level knowledge as learned directly from the robot's mouth—the Godot documentation.

Read the full message...
The reason I did this was two-fold:
  1. I wanted all resources to be as true to the current documentation as possible and filled with top-level expert information.
  2. I think it's important to make AI useful and that includes avoiding slop. A big part of that is ensuring the code we write follows the best practices set out by the Godot documentation and team itself.

My hope is that this agentic skillset will allow anyone to make a game if they wish and have it be good and natively, and proactively follow best practices. Not everyone is gifted with the detailed vocabulary specific to Godot they may need to make their dream game come true. I hope GDSkills acts as an assistant and expert in making them quickly come to reality.

I have many things I want to add to this project and a lot of testing and things I would like to do to ensure it continues to improve in quality over time.

Please enjoy and remember to use AI for good. Most importantly, have fun and dream big!

📜 Updates

The Expert Augmentation Update - v0.0.6

v0.0.6 — The Expert Augmentation & Master Orchestration Update

  • Microskill Overhaul: We spent many hours updating all microskills to contain top expert-level knowledge, directly extracted from the Godot documentation. This massive update ensures all resources are true to the current engine state, empowering developers with best practices and reducing AI slop.
  • Godot Master Takes Control: We updated the godot-master skill to fully orchestrate and integrate this major skill update. It is now a true, all-in-one Godot Master skill!
  • Feedback Requested: We'd love your feedback on the new updates! The easiest way to share your thoughts is to open an issue or start a discussion on our GitHub.

📜 Update Archive
The Looper Update - v0.0.5

v0.0.5 — The Looper Update

  • Resource Harvesting: Introduced godot-game-loop-harvest for interactive gathering, node depletion, and rarity-based drop tables.
  • Time Trials & Ghosts: Added godot-game-loop-time-trial with precise millisecond timing and ghost transform recording/playback.
  • Wave-Based Survival: Implemented godot-game-loop-waves for round-based difficulty scaling and dynamic enemy pool management.
The Easter & Renewal Update - v0.0.4

v0.0.4 — The Easter & Renewal Update

  • Seasonal Theming Identity: Introduced godot-theme-easter for safe, runtime aesthetic injection (StyleBox duplication & material swapping).
  • Core Loop Expansion: Added godot-game-loop-collection for volumetric procedural spawning and godot-mechanic-revival for "Souls-like" mortality.
  • Interaction Secrets: Implemented godot-mechanic-secrets for input sequence buffering (Konami code) and hidden discovery persistence.
The Romance Update - v0.0.3

v0.0.3 — The Romance Update

  • New Genre Mastery: Introduced the comprehensive Romance & Dating Sim skill set.
  • Master Integration: Unified the Romance skill into the godot-master orchestration layer.
  • Production Scripts: Added battle-tested GDScript patterns for affection tracking, relationship routing, and date events.

Master Skill Evolution - v0.0.2

v0.0.2 — Master Skill Evolution

  • Unified Architecture: Upgraded godot-master to an all-in-one orchestration layer for all 87 specialized skills.
  • Decision Matrix: Integrated expert-level Godot 4 architectural decision trees and anti-pattern guides.
  • Workflow Scaffolding: Added programmatic scene building and project initialization patterns.

Initial Launch - v0.0.1

v0.0.1 — Initial Launch

  • The Foundation: Released the initial library of 80+ Godot 4.x Agentic Skills.
  • Agent-First Design: Established the DIA (Discovery-Ingestion-Application) loop for AI Coding Agents.
  • Core Systems: Atomic implementations for 2D, 3D, UI, and Gameplay fundamentals.

📍 Quick Navigation

🚀 Get Started 🏆 Godot Master 🧩 Micro-Skills 🤖 Agent Protocol ⭐ Star History
Install All-in-One System Bite-Size Modules DIA Loop Growth Chart

The Philosophy

Godot Agentic Skills is a high-density, Agent-First knowledge library for Godot 4.5+—designed as an external "Long-Term Memory" (LTM) for AI Coding Agents. It provides structured, deterministic patterns for professional game and application engineering.

Unlike generic AI responses, every skill in this repository follows strictly defined Godot 4 best practices, architectural patterns, and performance optimization techniques refined by shipping real products.

If this project helps your development or empowers your agents, please give it a star! 🌟

⚡ Quick Start

Choose your path to avoid a "Context Storm" (overloading your agent with too many instructions at once).

🏆 Path A: The Architect (New or Existing Projects)

If you are starting a new project OR you have an existing project that needs to be "checked" and brought up to date with modern Godot 4 standards, install the Godot Master hub.

npx skills add thedivergentai/gd-agentic-skills/skills/godot-master

🧩 Path B: The Specialist (Existing Projects)

If you need a specific feature (e.g., 2D movement, inventory), install only that Micro-Skill.

npx skills add thedivergentai/gd-agentic-skills/skills/godot-characterbody-2d

[!DANGER]
NEVER use the --all flag when installing this repository (e.g., npx skills add ... --all). This is an "Instant No-No" that will cause an unrecoverable Context Storm by forcing your agent to read every single metadata entry in the library.

🧠 Context Management: Performance Guidelines

To keep your AI agent fast and accurate, follow these "Expert Efficiency" rules:

1. The "Power of One" Rule

Either use godot-master (which orchestrates the other 93 skills via references) OR use individual micro-skills.

  • Godot Master is an "Orchestrator" skill. It is dense (~15k tokens) but provides a complete blueprint. Use it when the "Big Picture" matters.
  • Micro-Skills are "Surgical" skills (~2-5k tokens). They are fast, reliable, and keep the agent focused on one specific API.

2. Why "Install All" Fails

Installing 94 skills simultaneously creates a "Metadata Flood":

  • Token Bleed: ~15,000 tokens are "permanently" used just to tell the agent which skills exist.
  • Instruction Conflicts: Having multiple overlapping expert instructions (e.g., 20+ different genre blueprints) can cause the agent to lose its specific focus.
  • Reasoning Lag: The model has to sift through 100+ KB of text before deciding what to do.

3. Repository Clones vs. Plugin Installs

  • Plugin Install (npx skills add): Copies the skill to your agent's Skill Plugin Directory. The agent can now "Discover" and scan these instructions automatically in any conversation. This is why installing too many at once causes a "Context Storm."
  • Repository Clone: If you merely clone this repo to a folder (e.g., Downloads/GDSkills), the agent will NOT automatically find them unless you are actively working inside that specific directory. This is safer for context management but requires manual view_file calls for discovery.

🏆 Godot Master — Your Lead Architect

The godot-master skill is the crown jewel of this repository—a consolidated expert library that orchestrates all 94 specialized skills into a unified architectural framework.

🎯 What Makes Godot Master Special?

Unlike individual micro-skills that focus on isolated features, godot-master is your system architect. It provides:

📚 Comprehensive Knowledge Base

  • 94 Reference Documents: Complete markdown guides for every skill, from foundations to advanced genres
  • 982 Unique Production Scripts: Battle-tested, production-ready GDScript implementations
  • 10 Workflow Patterns: Step-by-step architectural workflows (scaffolding, entity orchestration, persistence, optimization, multiplayer, etc.)

🧠 Expert Frameworks

  • Architectural Decision Matrix: Choose the right pattern for your project (component-driven, event-driven, resource-streaming, deterministic networking)
  • 15 Anti-Patterns: Explicit "NEVER DO THIS" rules with non-obvious explanations (e.g., why get_tree().root.get_node() breaks, why load() in _process kills performance)
  • Performance Budgets: Concrete numbers for mobile/desktop targets (draw calls, triangle counts, script time)
  • Server API Patterns: Expert escape hatch for 10K+ entities using RenderingServer/PhysicsServer RIDs

🏗️ The Layer Cake Architecture

Godot Master enforces a signal-based separation of concerns:

graph TD
    UI[🎨 PRESENTATION<br/>UI / VFX / Audio] -->|Signals ⬆️| LOGIC[⚙️ LOGIC<br/>State Machines / Controllers]
    LOGIC -->|Signals ⬆️| DATA[💾 DATA<br/>Resources / .tres / Stats]
    DATA -->|Signals ⬆️| INFRA[🌐 INFRASTRUCTURE<br/>Autoloads / Signal Bus / Managers]
    
    style UI fill:#1f2937,stroke:#58A6FF,stroke-width:2px,color:#fff
    style LOGIC fill:#1f2937,stroke:#79C0FF,stroke-width:2px,color:#fff
    style DATA fill:#1f2937,stroke:#A371F7,stroke-width:2px,color:#fff
    style INFRA fill:#1f2937,stroke:#F778BA,stroke-width:2px,color:#fff

Critical Rule: Signals travel UP only. Presentation layer never modifies Data directly. Infrastructure speaks exclusively through signals.

🔄 When to Use Godot Master vs Micro-Skills

flowchart LR
    START([New Task]) --> Q1{Starting a<br/>new project?}
    Q1 -->|Yes| MASTER[Use godot-master]
    Q1 -->|No| Q2{Need architectural<br/>guidance?}
    Q2 -->|Yes| MASTER
    Q2 -->|No| Q3{Building a<br/>complete system?}
    Q3 -->|Yes| MASTER
    Q3 -->|No| MICRO[Use micro-skill:<br/>targeted implementation]
    
    MASTER --> DESC1[✓ Full workflow context<br/>✓ Decision frameworks<br/>✓ Anti-patterns<br/>✓ Performance budgets]
    MICRO --> DESC2[✓ Quick implementation<br/>✓ Focused feature<br/>✓ Standalone pattern]
    
    style START fill:#1f2937,stroke:#58A6FF,stroke-width:3px,color:#fff
    style MASTER fill:#0d1117,stroke:#58A6FF,stroke-width:3px,color:#79C0FF
    style MICRO fill:#0d1117,stroke:#A371F7,stroke-width:3px,color:#F778BA
    style DESC1 fill:#1f2937,stroke:#58A6FF,stroke-width:2px,color:#fff
    style DESC2 fill:#1f2937,stroke:#A371F7,stroke-width:2px,color:#fff

Use godot-master when:

  • Starting a new Godot project from scratch
  • Auditing an existing project to find anti-patterns or standards violations
  • Designing game or application architecture
  • Building entity/component systems
  • Debugging performance or physics issues
  • Choosing between 2D/3D approaches
  • Implementing multiplayer
  • Optimizing draw calls or script time
  • Porting between platforms

Use micro-skills when:

  • Adding a specific feature to an existing codebase
  • Learning a targeted Godot API pattern
  • Implementing standalone functionality (UI component, particle effect, save system)

📖 Access Godot Master

# Skill path
skills/godot-master/SKILL.md

# Contains
├── 91 reference markdown files (references/)
├── 185 production scripts (scripts/)
└── Complete architectural decision trees

🧩 Micro-Skills — Bite-Size Power

Individual micro-skills are modular add-ons for targeted functionality. Each is atomic, self-contained, and production-ready—perfect for when you need a specific implementation pattern without the full architectural context.

Think of micro-skills as your component library: Drop them into your project for instant, expert-level functionality.

🏗️ Architecture & Foundation (11 skills)
🎮 2D Systems (10 skills)
🌍 3D Systems (6 skills)
⚔️ Gameplay Mechanics (13 skills)
🎨 UI & UX (5 skills)
🌐 Connectivity & Platforms (9 skills)
🔄 Adaptation Guides (5 skills)
🎯 Genre Blueprints (26 skills)

Action & Combat

Strategy & Tactics

Exploration & Adventure

Narrative & Puzzle

Simulation & Social

📂 Full Skill Index

All skills are catalogued in the machine-readable skills_index.json with keywords, descriptions, and dependency chains.

[!NOTE]
This JSON index is a repository-level file and is only present if you have cloned the source repository.

🤖 For Agents — The Discovery-Ingestion-Application Protocol

AI agents must follow the DIA loop for maximum quality:

1️⃣ Discovery

Query skills_index.json to find the skill matching the user's intent.

Example: User wants "smooth character movement" → Agent finds godot-characterbody-2d and godot-tweening.

2️⃣ Ingestion

CRITICAL: Agents MUST NOT implement from general training data alone.

Required: Use view_file on the skill's SKILL.md to catch Godot 4-specific nuances (e.g., AudioServer.get_time_since_last_mix() for rhythm sync, StringName for O(1) dictionary lookups).

For complex projects: Load godot-master for architectural workflows and anti-patterns.

3️⃣ Application

Follow the Skill Chain documented in the skill header. Apply patterns recursively, starting from the deepest dependency.

Example Workflow:

User: "Build a player controller"
Agent: Query skills_index.json → Find godot-characterbody-2d
Agent: Read godot-characterbody-2d/SKILL.md → See dependencies: godot-composition, godot-state-machine-advanced
Agent: Read godot-composition/SKILL.md → Implement component architecture first
Agent: Read godot-state-machine-advanced/SKILL.md → Build state machine layer
Agent: Return to godot-characterbody-2d → Implement movement with components + states

🚨 Anti-Erosion Policy

Documentation MUST remain in sync with implementation. If a Godot 4 API changes, update the relevant SKILL.md immediately.

🏗️ Infrastructure Integration

MCP Server Support

These skills integrate seamlessly with the Godot MCP Server:

  • godot-mcp-scene-builder: Programmatic scene generation
  • godot-mcp-setup: Server configuration and diagnostics

Project Standards

All code follows Godot 4.5+ conventions:

  • Static typing: func move(vec: Vector2) -> void:
  • Signal / Callable / Tween (Godot 4 syntax)
  • StringName for performance-critical lookups
  • Component composition over deep inheritance

🤝 Contributing

We welcome contributions from developers and agents!

📖 Read the full contribution guide: CONTRIBUTING.md

Quick Guidelines:

  • Every skill must provide Expert Knowledge Delta (not tutorials)
  • Include anti-patterns with non-obvious explanations
  • Code must be Godot 4.5+ native, statically typed
  • Scripts must parse without warnings

Submit: Open an issue with [Request] tag or submit a PR describing the knowledge delta your skill adds.

⭐ Star History

If this project accelerates your Godot development or empowers your AI agents, consider starring the repository! ⭐

Star History Chart

📊 Repository Stats

Metric Value
Total Skills 94
Genre Blueprints 27
Production Scripts 982
Reference Documents 94
Target Engine Godot 4.5+
License LGPLv3

💖 Sponsorship & Support

We are seeking financial sponsors and infrastructure partners to sustain the Godot Agentic Ecosystem. Every contribution helps us maintain these skills and keep them free for the community.

🚀 View our Sponsorship & Support Opportunities

Get in Touch: [email protected]

📜 License

This project is licensed under the GNU Lesser General Public License v3.0 - see LICENSE for details.

Why LGPLv3?
We chose this license because it strikes the perfect balance for an open ecosystem. It ensures that any improvements or additions made directly to the GDSkills library itself remain open-source and shared with the community. At the same time, it empowers you to use these agentic skills to build and compile your own incredible games, which you are completely free to commercialize and keep closed-source if you wish.

By contributing, you agree that your code will be licensed under the project's LGPLv3 License.

Authored by Divergent AI
Maintained by the Agents

[!IMPORTANT]
Anti-Erosion Policy: Documentation MUST remain in sync with implementation. If a Godot 4 API changes, update the relevant SKILL.md immediately.