jogos_matheus/.claude/skills/vitruvio-criar-query/SKILL.md

name, description

name	description
vitruvio-criar-query	Use when the user wants to create a new named SQL query in a Vitruvio repository. Triggers: "create query", "new query", "criar query", "nova query", "add query", "named query", or any request to scaffold a queries/*.sql file and register it in vitruvio.json.

Create Vitruvio Query

All messages shown to the user must be written in Portuguese.

You are creating a new named SQL query inside a Vitruvio repository. Follow these steps in order.

Step 1 — Confirm you are inside a Vitruvio repo

ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"

If NOT_A_VITRUVIO_REPO, stop and tell the user to cd into the correct repo.

Step 2 — Collect query details

Ask the user (in a single message, only ask what is missing from their original request):

• Key — kebab-case unique identifier. Used to reference this query in reports, DBTable components, and scripts.
• Name — human-readable label shown in the Vitruvio UI.
• SQL — the query itself, or enough context to write it.
• Connection — datasource name (default: vitruvio_producao). Ask only if the user mentions a specific datasource.

Step 3 — Scaffold and create file

vitruvio new query <key> --name "<name>"

This creates queries/<key>.sql and registers it in vitruvio.json with connection: "vitruvio_producao". Replace the generated SQL with the actual query. If a different datasource is needed, update "connection" in vitruvio.json.

Target path: queries/<key>.sql

Rules:

• One SELECT per file. No multiple statements, no DDL, no INSERT/UPDATE/DELETE.
• Named bind parameters use :paramName syntax — never concatenate user input into SQL.
• Write ANSI SQL where possible. If DB-specific syntax is unavoidable, note it in a comment.
• Keep Oracle and PostgreSQL compatibility in mind — avoid syntax that only works in one.

SELECT col1,
       col2
  FROM my_table
 WHERE active = 1
   AND id = :id
 ORDER BY col1

Step 4 — Update vitruvio.json entry

vitruvio new already added the query entry. The full entry shape is:

{
  "key": "<key>",
  "name": "<name>",
  "source": "queries/<key>.sql",
  "connection": "vitruvio_producao"
}

Update "connection" only if the user specified a datasource other than "vitruvio_producao".

Step 5 — Report

Tell the user:

• File created: queries/<key>.sql
• Registered in vitruvio.json with key <key>
• How it can be used: as a datasource in a report, in a DBTable component, or loaded in a script via db.executeNamedQuery('<key>', params)