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

A comprehensive, high-fidelity reference for the Crystal programming language (v1.20.3), 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.3 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.3, including the Sync module, modern Time APIs, and spec protocols.

Installation

To install the skill in your current workspace:

.. code-block:: bash

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

To install it globally for your user:

.. code-block:: bash

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

After installation, reload your session to activate the skill:

.. code-block:: bash

   /skills reload

LLM Benchmarking
----------------
We include a specialized tool, ``scripts/llm_benchmark.bash``, to evaluate LLM performance against Crystal v1.20 idioms. It compares a "Naked Baseline" against a "System Override" (using our documentation as a system prompt) to measure compliance with modern memory safety and concurrency standards.

Usage:

.. code-block:: bash

   ./scripts/llm_benchmark.bash [gemini|claude|openai]

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.3.3 revision.

Related Projects
----------------

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

License
-------
This project is licensed under the terms of the **GNU Free Documentation License, Version 1.3** or any later version published by the Free Software Foundation. See the ``LICENSE`` file for details.

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>`_