================== Crystal for Agents

A comprehensive, high-fidelity reference for the Crystal programming language (v1.20.0), specifically optimized for AI agents and LLMs.

Overview

This project provides a centralized "source of truth" for Crystal development. It distills the official documentation, standard library patterns, and v1.20.0 standards into a format that AI agents can use to generate safe, idiomatic, and performant code.

Crystal Philosophy: "Fast as C, slick as Ruby" - static typing, compiled performance, and expressive syntax.

Gemini Expert Skill

We provide a portable Gemini Skill that encapsulates this entire reference. Once installed, it gives your agent "Expert" knowledge of Crystal v1.20.0, including the Sync module, modern Time APIs, and spec protocols.

Installation

To install the skill in your current workspace:

.. code-block:: bash

   gemini skills install agents/gemini/crystal/ --scope workspace

To install it globally for your user:

.. code-block:: bash

   gemini skills install agents/gemini/crystal/ --scope user

After installation, reload your session to activate the skill:

.. code-block:: bash

   /skills reload

Document Structure
------------------
The reference is built from modular files in the ``sections/`` directory, ranging from core types (``01-types.rst``) to advanced concurrency (``05-concurrency.rst``) and operational directives (``19-directives.rst``).

The master ``crystal.rst`` is auto-generated from these sections.

Development & Building
----------------------
This project uses a ``GNUmakefile`` to manage the build process.

.. code-block:: bash

   # Compile everything (RST, PDF, and syntax check)
   make all

   # Check RST syntax only
   make check-rst

   # Update local reference sources (shards, crystal-book)
   make update-references

Contributing
------------
Please read ``CONTRIBUTING.rst`` for technical standards and the "Verification Loop" protocol. All changes must be made in the ``sections/`` directory and validated via ``make check-rst``.

Changelog
---------
See ``CHANGELOG.rst`` for a detailed history of updates, including the Crystal v1.20.0 alignment.

Related Projects
----------------
* `crystal-mcp <https://gitlab.com/renich/crystal-mcp>`_ - Model Context Protocol (MCP) implementation for Crystal.

References
----------
* `Official Crystal Reference <https://crystal-lang.org/reference/latest/>`_
* `Crystal API Docs <https://crystal-lang.org/api/latest/>`_
* `Crystal GitHub Repository <https://github.com/crystal-lang/crystal>`_