jogos_matheus/.claude/skills/vitruvio-registrar-artefato/SKILL.md

name, description

name

description

vitruvio-registrar-artefato

Use when the user has an existing file they want to add to a Vitruvio repository. Triggers: "I have an existing file", "move this to panels/", "register this artifact", "add this already existing", "tenho um arquivo pronto", "mover para o repo", or any request where the source file already exists and needs to be placed in the correct repo directory and registered in vitruvio.json. Do NOT use vitruvio-criar-* skills for this — those scaffold new files and would overwrite the existing one.

Register Existing Artifact

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

You are wiring an already-existing file into a Vitruvio repository. No scaffolding — the file exists and must be placed correctly then registered in vitruvio.json. 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 details

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

• Source file path — where the file currently lives (absolute or relative).
• Artifact type — one of: panel, script, endpoint, query, report, library, process.
• Key — kebab-case unique identifier for this artifact. Must be unique within its section in vitruvio.json. Changing it later is a breaking change.
• Name — human-readable label shown in the Vitruvio UI.
• Type-specific fields (only ask what is relevant):
  • Panel: category (e.g. "Base de Conhecimento"), openInNewWindow (default true), showInMobileList (default false), mobile form path if one also exists.
  • Script: domain — USUARIO (default) or SISTEMA.
  • Endpoint: authMode — PUBLIC (default), STATIC_TOKEN, VITRUVIO_WS_USER_AUTH, or HTTP_BASIC_AUTH.
  • Query: connection — datasource name (default vitruvio_producao).
  • Report: type — MODELO_ESTATICO or DINAMICO_QUERY_SQL; query key; template path; parameterForm path (optional).
  • Library: authMode — PUBLIC (default); mobileEnabled (default false).
  • Process: path to the BPMN file and desktop form XML if they are separate files.

Step 3 — Place the file(s)

Create the destination directory if it does not exist, then move the source file to the correct location. Never call vitruvio new — it would scaffold and overwrite the existing file.

Artifact	Destination	Notes
panel	panels/<key>/<key>-desktop.xml	Rename the source desktop form to <key>-desktop.xml. If a mobile form also exists, place it at panels/<key>/<key>-mobile.xml.
script	scripts/<key>.js
endpoint	endpoints/<key>.js
query	queries/<key>.sql
report	reports/<key>/	Move jrxml and optional params.xml into this directory.
library	libraries/<key>/	Move all files into this directory.
process	processes/<key>/	Move the .bpmn and form XML(s) into this directory.

# Example: panel
mkdir -p panels/<key>
mv /path/to/source.xml panels/<key>/<key>-desktop.xml

Step 4 — Add entry to vitruvio.json

Read vitruvio.json. If the relevant section array does not exist, create it. Append the entry for the artifact type. Do not remove or modify any existing entries.

Panel

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "category": "<category>",
  "displayOrder": 10,
  "showInPresentation": false,
  "openInNewWindow": true,
  "showInMobileList": false,
  "displayTimeInSeconds": 0,
  "allowedGroups": [],
  "allowedUsers": [],
  "forms": {
    "desktop": "panels/<key>/<key>-desktop.xml",
    "mobile": null,
    "mobileAlternative": null
  },
  "defaultState": null,
  "thumbnail": null
}

Script

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "language": "javascript",
  "domain": "USUARIO",
  "source": "scripts/<key>.js"
}

Endpoint

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "language": "javascript",
  "authMode": "PUBLIC",
  "active": true,
  "source": "endpoints/<key>.js"
}

Query

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

Report

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "type": "DINAMICO_QUERY_SQL",
  "category": "<category or omit>",
  "owner": null,
  "template": "reports/<key>/template.jrxml",
  "parameterForm": "reports/<key>/params.xml",
  "query": "<query-key>",
  "orientation": "RETRATO",
  "allowedGroups": [],
  "allowedUsers": []
}

Library

{
  "key": "<key>",
  "name": "<name>",
  "type": "LOCAL",
  "authMode": "PUBLIC",
  "authToken": null,
  "mobileEnabled": false,
  "files": "libraries/<key>/"
}

Process

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "bpmn": "processes/<key>/<key>.bpmn",
  "forms": {
    "desktop": "processes/<key>/<key>-desktop.xml",
    "mobile": null,
    "mobileAlternative": null
  }
}

Step 5 — Report

Tell the user:

• Where the file was placed
• Registered in vitruvio.json under section <type> with key <key>
• Which fields were left at defaults and may need updating (e.g. category, allowedGroups, description)
• Reminder: keys are stable identifiers — changing them later is a breaking change