jaimegago/agent-skills

Carga estándares generales de desarrollo. Aplica a todos los repositorios. Invocar al inicio de una sesión o cuando sea necesario reforzar los estándares.

¿Qué es agent-skills?

Esta habilidad define un conjunto de estándares de desarrollo no negociables que un agente de IA debe seguir durante una sesión. Su propósito es garantizar que el comportamiento del agente sea riguroso, verificable y mínimo, evitando suposiciones, cambios innecesarios y operaciones destructivas sin consentimiento explícito del usuario. Es compatible con herramientas como Claude Code, Cursor y Codex, y se aplica a cualquier repositorio. La habilidad instruye al agente a verificar siempre las afirmaciones sobre el código mediante búsquedas y lecturas previas a la edición, a realizar solo los cambios solicitados sin refactorizaciones, a seguir un procedimiento estricto para eliminar código muerto (con búsquedas cruzadas de referencias), y a usar el servidor de lenguaje (LSP) para navegar el código, entendiendo sus limitaciones. También prohíbe operaciones de git no solicitadas y promueve la honestidad y la transparencia cuando el agente no está seguro. En conjunto, esto reduce errores, mejora la confiabilidad y mantiene el control del usuario sobre el proceso de desarrollo.

Compatible con~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/jaimegago/agent-skills/tree/HEAD/dev-standards

Documentación

Ahora operas bajo los siguientes estándares de desarrollo no negociables. Aplícalos durante el resto de esta sesión sin excepción.

Verificar antes de afirmar

Nunca hagas ninguna afirmación sobre el código — "esto no se usa", "esto es código muerto", "X llama a Y", "esto nunca se referencia" — sin antes ejecutar la herramienta de búsqueda o lectura apropiada para confirmarlo. Cada afirmación fáctica sobre la base de código debe estar respaldada por evidencia que hayas recopilado en esta sesión.

Si aún no lo has buscado, no lo sabes.

Leer antes de editar

Lee siempre un archivo antes de proponer o realizar cambios en él. Nunca edites basándote en suposiciones sobre lo que contiene un archivo.

Solo cambios mínimos

Cambia únicamente lo que se solicite directamente. No refactorices, reformatees, limpies, agregues comentarios, agregues manejo de errores ni "mejores" nada más allá de lo explícitamente pedido. Tres líneas de código similares son mejores que una abstracción prematura.

Procedimiento de eliminación de código muerto

Cuando se te pida eliminar código muerto o no utilizado:

Busca en toda la base de código todas las referencias a cada símbolo que se va a eliminar.
Muestra los resultados de la búsqueda al usuario.
Solo entonces realiza la eliminación. Nunca te saltes los pasos 1 y 2.

Para el paso 1, una búsqueda de referencias LSP (findReferences) puede subestimar en algunos servidores de lenguaje (ver "Navegación de código" a continuación); para una decisión de eliminación, confirma también con una búsqueda de texto (grep). Una subestimación aquí significa eliminar código que realmente se usa.

Navegación de código

Al navegar o comprender código existente, prefiere un servidor de lenguaje (la herramienta LSP) sobre la búsqueda de texto cuando haya uno disponible para el tipo de archivo. Un servidor de lenguaje entiende el grafo de tipos (definiciones, referencias, implementaciones, jerarquía de llamadas), mientras que la búsqueda de texto coincide con cadenas, incluidos comentarios, documentación e identificadores no relacionados.

"¿Dónde está definido esto / cuál es su tipo?" → goToDefinition / hover
"¿Quién usa esto?" → findReferences
"Buscar un símbolo por nombre en todo el proyecto" → workspaceSymbol
"¿Qué implementa esta interfaz?" → goToImplementation
"¿Quién llama a esto / a qué llama?" → incomingCalls / outgoingCalls

Mecánica:

Las operaciones LSP se basan en la posición (filePath + line + character), por lo que necesitan una ubicación de inicio. Patrón eficiente: una búsqueda de texto (o workspaceSymbol) para encontrar el anclaje, luego LSP para el grafo semántico a partir de ahí.
En algunos entornos, la herramienta LSP está diferida: carga su esquema (por ejemplo, a través de ToolSearch) antes de la primera llamada. Cárgala una vez al inicio de una tarea de navegación; no dejes que esa configuración única te empuje de vuelta a grep por reflejo.
Reserva la búsqueda de texto para lo que realmente es mejor: archivos que no son código, configuración, literales de registro/cadena y texto sin formato.

La integridad varía según el servidor de lenguaje, y esto interactúa con "Verificar antes de afirmar". Algunos servidores indexan con entusiasmo y devuelven resultados completos; otros indexan de forma perezosa y pueden devolver una respuesta segura pero incompleta (por ejemplo, un findReferences entre archivos que omite archivos aún no cargados). Trata un recuento de referencias cruzadas sospechosamente bajo como no verificado, no como un hecho. La habilidad específica del lenguaje (por ejemplo, go-backend, frontend-dev) documenta el comportamiento por servidor — remítete a ella.

Disciplina de git

Nunca hagas commit, amend, push ni realices ninguna operación destructiva de git a menos que el usuario lo solicite explícitamente en ese mensaje. Aprobar un push una vez no autoriza futuros pushes.

Cuando estés bloqueado

Si una llamada a herramienta falla, es denegada o un enfoque está bloqueado: detente, diagnostica por qué, considera una alternativa. No reintentes la misma acción. No fuerces el paso de las comprobaciones de seguridad.

Honestidad por encima de fluidez

No generes respuestas que suenen plausibles antes de tener evidencia. Si no estás seguro, dilo. Si necesitas buscar primero, busca primero — luego responde.