@robosophy/skills

Skills de agentes de IA compartidas por los frontends BASF, con un instalador que las deja donde cada herramienta las busca.

Una skill es un archivo Markdown con instrucciones: un procedimiento que el agente sigue cuando la tarea lo amerita. No es específica de ninguna herramienta y no hay nada que compilar.

Uso

# Ver qué hay disponible
npx @robosophy/skills list

# Para vos, en todas tus herramientas y todos tus proyectos
npx @robosophy/skills install qa-checklist --global

# Para este repo y todo el equipo que trabaje en él
npx @robosophy/skills install qa-checklist

Qué destino elegir

| Quiero que la use... | Comando | Dónde queda | | --- | --- | --- | | Yo, en todas mis herramientas | install <skill> --global | ~/.agents/skills/ + symlinks | | Todo el equipo, en este repo | install <skill> | .agents/skills/ + puntero en AGENTS.md | | Claude Code, en este repo | install <skill> --claude | .claude/skills/ | | Una herramienta puntual | install <skill> --dir <ruta> | <ruta>/<skill>.md |

Agregá --force para sobrescribir algo que ya exista.

Instalación global

npx @robosophy/skills install qa-checklist --global

Guarda una sola copia en ~/.agents/skills/<nombre>/SKILL.md y crea un symlink en la carpeta de cada herramienta que tengas instalada:

| Herramienta | Se enlaza en | Ruta verificada | | --- | --- | --- | | Claude Code | ~/.claude/skills/<nombre> | sí | | Codex | ~/.codex/skills/<nombre> | sí | | Cursor | ~/.cursor/skills-cursor/<nombre> | sí | | Gemini | ~/.gemini/config/skills/<nombre> | sí | | OpenCode | ~/.config/opencode/skills/<nombre> o ~/.opencode/skills/<nombre> | no |

Ninguna de esas herramientas lee ~/.agents/skills por su cuenta: el almacén es neutral y el symlink es lo que la hace visible. Al haber una sola copia, actualizarla las actualiza a todas de una vez.

La ruta de OpenCode es la convencional y no está verificada contra una instalación real. Si la tuya usa otra, agregala a TOOL_LINKS en bin/cli.mjs o usá --dir. Una ruta equivocada no rompe nada: al no existir la carpeta, simplemente no enlaza.

Solo enlaza en las herramientas que ya tengas instaladas, y nunca pisa una carpeta que ya exista: la omite y avisa, salvo que pases --force. Si el sistema no permite crear symlinks —Windows sin modo desarrollador—, copia el archivo y lo aclara en la salida.

Instalación por repo

npx @robosophy/skills install qa-checklist

Escribe la skill en .agents/skills/<nombre>.md y agrega a AGENTS.md un puntero con la condición de cuándo leerla. Commiteá los dos archivos y le llega a todo el equipo.

AGENTS.md es la convención que leen Codex, OpenCode, Cursor y Copilot, pero se carga en cada pedido. Por eso el instalador no mete la skill entera ahí: pagarías ese texto en contexto aunque estés haciendo cualquier otra cosa. En su lugar deja solo el puntero, igual que el patrón .agents/rules/ que ya usan los repos BASF:

<!-- robosophy-skills:start -->
## Skills

Cuando la tarea coincida con alguna de estas, leé y seguí el archivo indicado antes de trabajar:

- `.agents/skills/qa-checklist.md` — Genera un listado de QA en castellano a partir de...
<!-- robosophy-skills:end -->

Respeta lo que ya hubiera en el archivo. El bloque es una lista: instalar más skills las acumula, y reinstalar una actualiza su línea en vez de duplicarla.

Claude Code no lee .agents/skills/, así que si el equipo lo usa, sumá también --claude para dejarla en .claude/skills/<nombre>/SKILL.md.

Una carpeta puntual

Cada herramienta guarda sus reglas donde quiere. En vez de adivinar, se la pasás:

npx @robosophy/skills install qa-checklist --dir .cursor/rules
npx @robosophy/skills install qa-checklist --dir ~/.config/alguna-ia/reglas

Escribe <ruta>/<skill>.md sin el frontmatter —que solo usa Claude Code— y no toca AGENTS.md, porque el puntero apuntaría a un lugar equivocado. Acepta ~. Combinado con --claude usa el layout <ruta>/<skill>/SKILL.md con frontmatter.

Y si preferís manejarlo vos, print la escupe por stdout:

npx @robosophy/skills print qa-checklist > reglas/qa.md
npx @robosophy/skills print qa-checklist | clip     # al portapapeles, en Windows

No existe un AGENTS.md global compartido: cada herramienta tiene el suyo (~/.codex/AGENTS.md, por ejemplo) y el de un repo es por repo. Si querés apuntar a uno de esos, usá --dir.

Skills del catálogo

qa-checklist

Arma un listado de QA a partir de los cambios de una rama o un MR, agrupado por pantalla, con ruta, rol, cómo llegar y qué verificar. Entrega Markdown listo para pegar en un comentario de GitLab.

Lo que aporta sobre pedirlo a mano: acota el diff a lo que la rama realmente aporta —sin arrastrar trabajo de otros—, incluye lo que todavía no está commiteado, agrupa por pantalla en vez de por archivo, y marca explícitamente qué tenía más riesgo de romperse y por qué.

Se invoca con /qa-checklist en las herramientas que soporten comandos, o pidiéndosela en lenguaje natural: "armame el listado de QA de esta rama".

mr-review

Hace de reviewer senior sobre el diff de una rama: se para en la rama, deduce contra qué base comparar, saca el diff y devuelve los hallazgos ordenados por severidad —blocker, major, minor— con archivo y línea, un comentario corto para pegar en el MR y el arreglo recomendado.

Lo que aporta sobre pedirlo a mano: infiere la base del sufijo de la rama (-dev → dev, sin sufijo → prod) y la verifica antes de analizar, así el review no arrastra trabajo ajeno; usa la línea del archivo final en vez de la del diff, que es la que se puede cliquear; y separa el código realmente nuevo del que un refactor sólo movió, para no ahogar los hallazgos reales con problemas preexistentes.

Se invoca con /mr-review, o "revisá el MR de la rama 1723-notifications-dev".

self-review

El mismo review, sobre tu propio trabajo antes de abrir el MR. Incluye lo que todavía no commiteaste, y en vez de comentarios para GitLab devuelve el fix concreto de cada problema y un plan de arreglo ordenado. No edita código: al cierre ofrece pasar a modo plan para ejecutarlo.

Se invoca con /self-review, o "revisá lo que hice antes de subirlo".

Salida en el chat, no en un archivo

Las dos skills de review responden en el chat. Las referencias van como src/assets/css/app.css:4, sin backticks: así se pueden cliquear y abren el archivo en esa línea. En un .md o en un Artifact eso se pierde, que es justo lo que hace accionable al review. qa-checklist, en cambio, sí entrega un .md, porque su destino es un comentario de GitLab.

Agregar una skill al catálogo

1. Creá skills/<nombre>/SKILL.md con frontmatter name y description. La description es lo que el agente lee para decidir si la skill aplica: escribila incluyendo las frases con las que alguien pediría esa tarea.
2. Subí la version del package.json.
3. npm publish -w @robosophy/skills

No hace falta tocar el CLI: el catálogo se arma leyendo el directorio skills/.