Agent Skills

SQL Helper

Генерация SQL-запросов из текстового вопроса и DDL-схемы.

Загружай этот скилл когда нужно превратить вопрос на естественном языке в SQL: для быстрых запросов к базе, разбора плана выполнения или форматирования SQL.

🎯 When to use

Use this skill when:

• Есть DDL-файл (CREATE TABLE) и вопрос, по которому нужен SQL-запрос
• Нужно быстро собрать SELECT/JOIN/GROUP BY/COUNT по шаблону
• Просят «сгенерируй sql», «напиши sql», «sql запрос», «sql helper»
• Нужно посмотреть план выполнения запроса (EXPLAIN) в читаемом виде

Do NOT use when:

• Нужна только проверка синтаксиса без схемы — достаточно обычного редактора
• Нужна миграция или генерация DDL — это отдельный инструмент
• Вопрос не про SQL (анализ данных, CSV, скрейпинг) — это другие скиллы

📦 Files

• SKILL.md — этот файл
• scripts/sql_helper.py — генератор SQL + EXPLAIN (Python 3 stdlib)
• references/canonical-patterns.md — канонические аналоги text-to-SQL и разбор недостающих техник

Canonical analogues

Полный разбор — в references/canonical-patterns.md. Ключевые каноны, на которые опирается дизайн скилла:

• Anthropic Cookbook capabilities/text_to_sql — эталон интроспекции схемы (sqlite_master + PRAGMA table_info) и execution-based валидации через promptfoo-ассерты.
• sqlsure / sql-semantic-check — семантические правила FANOUT/JOIN_KEY/ADDITIVITY и интроспекция PK/FK вместо эвристик join.
• Vanna.ai — контур train → retrieve (few-shot) → generate_sql → run_sql → verify.
• Spider / BIRD / Spider 2.0 — методология оценки: exact match, execution accuracy, validity + efficiency; schema linking как первый этап.
• sqlite-utils + SQLGlot — CLI-интроспекция (schema, analyze, memory) и квотинг идентификаторов (quote_identifiers).
• grok-sqlite-explain — построение дерева EXPLAIN по ссылкам parent, а не по id.

🧰 Usage

# Сгенерировать SQL по вопросу:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "select users by id"

# С планом выполнения:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "count orders by user" --explain

# JOIN двух таблиц:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "join users and orders"

# С лимитом и сортировкой:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "top 5 orders by date desc"

🔬 Проверка результата

• Скрипт выводит сгенерированный SQL в stdout и завершается с кодом 0.
• При --explain после SQL печатается секция --- query plan --- с планом.
• Пустой вопрос или невалидный DDL — сообщение в stderr и код выхода 1.

Boundaries

• Do not use for executing SQL against production or for schema migrations; review and run queries separately.

Evidence and completion gate

Run the documented command against the user’s actual input. Report the command, exit status, files changed or produced, and relevant stdout/stderr. Separate blocked or pre-existing failures from failures introduced by the current work. Do not call the result complete when the script was only described or when an artifact was not reopened and checked.

This site is open source. View this page on GitHub.