Skill ast-grep: buscar código por estructura sintáctica, no solo por texto

Para quién

Usa esta skill cuando quieras que un asistente de programación busque por estructura de código (árbol de sintaxis abstracta), no solo por coincidencia de texto. Oficialmente está en el mercado de complementos de Claude Code y aporta la búsqueda estructural de ast-grep.

Requisitos previos: ast-grep ya está instalado en esta máquina, y el asistente puede instalar skills. La guía no dice cómo instalar ast-grep en sí; no inventes un instalador. La guía nombra Claude Code; no presentes otros clientes como exclusivos oficiales. Si se puede usar fuera de ese conjunto nombrado, el texto original no lo dice.

Solo hay una ruta de instalación: un único comando npx. Tras instalar, debes pedir explícitamente usar la skill en la pregunta, por ejemplo "Use ast-grep to find...". La guía indica que en noviembre de 2025 Claude Code aún no puede decidir automáticamente usar ast-grep en todas las situaciones adecuadas. La guía no nombra un directorio de destino; tras instalar, confirma solo en el asistente actual que la skill se puede invocar por nombre.

Primer intento en 3 minutos

Página oficial:

https://github.com/ast-grep/agent-skill

Confirma primero que ast-grep local funciona y luego ejecuta la instalación recomendada (escribe archivos de skill en esta máquina; comprueba primero el nombre del repositorio):

npx skills add ast-grep/agent-skill

Si el comando falla, detente. Tras el éxito, no cambies primero el código de la aplicación. Abre un repositorio existente y di con claridad en lenguaje natural: Use ast-grep to find..., más un objetivo estructural de bajo riesgo, por ejemplo buscar cierta forma de llamada a función. Pide al asistente que primero analice si ast-grep encaja, escriba ejemplos y reglas de coincidencia, y pruebe primero en los ejemplos.

Señal de éxito: el asistente usó ast-grep de forma explícita, la regla quedó comprobada en los ejemplos y los resultados de todo el repositorio incluyen rutas de archivo y números de línea. Si quiere escribir un archivo de reglas o cambiar código de la aplicación, detenlo primero y confirma los efectos secundarios antes de seguir.

Casos de uso

Caso 1: búsqueda estructural de solo lectura. La pregunta debe nombrar ast-grep de forma explícita. Haz que el asistente encuentre coincidencias por estructura y devuelva rutas de archivo y números de línea. En la primera pasada, mira solo los resultados; no dejes que refactorice de paso. La guía no da un alcance de lenguajes ni un repositorio de ejemplo; no infieras a partir de una lista de lenguajes imaginada.

Caso 2: escribir primero la regla, comprobarla y al final buscar en todo el repositorio. Los pasos de la guía son: analizar si la consulta encaja con ast-grep, crear código de ejemplo para la coincidencia, escribir la regla, probarla en el ejemplo, buscar en toda la base de código solo si eso pasa, y al final dar rutas y números de línea. La búsqueda en todo el repositorio solo se permite si la prueba de ejemplo pasa. La guía no escribe una ruta de archivo de reglas ni flags de CLI; no inventes lo que falta.

Límites

La ruta principal solo documenta:

npx skills add ast-grep/agent-skill

Esta máquina necesita ast-grep ya instalado. El disparo debe nombrarlo de forma explícita, por ejemplo "Use ast-grep to find..."; no esperes que lo elija automáticamente en todas las situaciones.

La capacidad solo está evidenciada para la búsqueda estructural y la cadena «ejemplo → regla → prueba → repositorio entero → ruta y número de línea». Está escrito como una skill del mercado de complementos de Claude Code, pero en el primer intento no cambies a pasos de clic del mercado que nunca aparecen.

La guía no documenta comandos de instalación de ast-grep, facturación, alcance de lenguajes ni directorio de destino. El primer intento es solo una consulta de solo lectura; no lo trates como entrada a una refactorización. Lo que no tiene base permanece desconocido; no inventes operaciones.