Conceptos básicos de Habilidades de Agente

Qué contiene una Habilidad de Agente de Experto en Go y cuándo invocarla - diez ejemplos para equipos que usan asistentes de IA en Go 1.26.x. Estas páginas documentan habilidades, no código de aplicación. Una habilidad es un playbook SKILL.md que tu agente lee antes de actuar.

Prerrequisitos

Las habilidades residen en tu repositorio (o registro de habilidades del equipo) junto al módulo que gobiernan:

.cursor/skills/
├── go-api-design-review/
│   └── SKILL.md
├── go-concurrency-review/
│   └── SKILL.md
├── go-module-audit/
│   └── SKILL.md
└── go-testing-benchmark/
    └── SKILL.md

Fija la pila en cada encabezado de habilidad para que los agentes nunca se desvíen a APIs obsoletas:

## Fija de pila
- Go 1.26.x (verificar parche en la compilación)
- golangci-lint (conjunto de linters del equipo)
- HTTP: stdlib net/http según ADR-014 (o chi - verificar en la compilación)

Alcance: Las habilidades orquestan cómo debe trabajar un agente. Los manuales legibles por humanos en Conceptos básicos de net/http, Conceptos básicos de pruebas en Go y Conceptos básicos de seguridad en Go siguen siendo la referencia autorizada.

Ejemplos básicos

1. Qué es una Habilidad de Agente

Una Habilidad de Agente es un archivo de instrucción estructurado - típicamente SKILL.md - que le dice a un asistente de IA qué hacer, qué pedir y qué no hacer en una tarea de Go.

• Las habilidades no son tutoriales de funciones - son contratos operativos para el desarrollo asistido
• Las habilidades deben estar fijadas con Go - los agentes tienen alucinaciones de enrutamiento pre-1.22 sin contexto de versión explícito
• Una habilidad = un dominio de decisión (revisión de concurrencia, auditoría de módulos, diseño de API, RBAC del operador)

2. Estructura mínima de SKILL.md

Cada habilidad de Go debe comenzar con el mismo esqueleto:

# Habilidad de Revisión de Diseño de API en Go
 
## Qué hace esta habilidad
Revisa manejadores de net/http en busca de contexto, errores y códigos de estado.
 
## Cuándo invocar
- Antes de fusionar cambios de manejador
- Al generar un nuevo paquete REST
- Cuando el agente redacta cadenas de middleware
 
## Entradas (requeridas)
- go.mod, paquetes afectados, ADR de manejo de errores del equipo
- Elección del enrutador: stdlib ServeMux vs chi/gin
 
## Salidas
- Lista de verificación de revisión con hallazgos de archivo:línea
- Correcciones sugeridas (sin fusión automática)
- Verificación: go test ./..., golangci-lint run
 
## Salvaguardas
- Nunca elimines plazos de contexto en llamadas salientes
- Nunca devuelvas 500 para errores de validación
- Nunca deshabilites linters sin excepción de ADR
 
## Fija de pila
Go 1.26.x · golangci-lint · net/http (ADR-014)
 
## Prompts de ejemplo
Ver §10 abajo.

• Las entradas evitan que el agente adivine la ruta del módulo u omita enlaces de ADR
• Las salidas deben ser verificables - comandos, no prosa
• Las salvaguardas son la sección de mayor valor - los agentes refactorizan en exceso sin ellas

3. Cuándo invocar vs Cuándo leer la documentación

• Invoca habilidades en puntos de decisión donde la automatización incorrecta es costosa
• Lee documentación cuando aprendes conceptos - las habilidades asumen que quieres un plan ejecutable ahora

4. Entradas que el Agente Debe Recopilar

Antes de ejecutar, una habilidad bien escrita obliga al agente a recopilar:

## Lista de verificación de entradas
- [ ] go.mod y go.sum (ruta del módulo, directiva de versión de Go)
- [ ] Paquetes afectados (`./internal/api/...`)
- [ ] ADRs del equipo para errores, registro, autenticación
- [ ] Comandos de CI (test, lint, race, vuln)
- [ ] Elección del framework si no es stdlib (chi, gin, echo, gRPC)
- [ ] Contexto del incidente (si es triaje): instantánea de pprof, ruta de volcado de goroutine

• La ruta del módulo faltante rompe las sugerencias de importación y los comandos de prueba
• Los enlaces de ADR faltantes producen un manejo de errores genérico que entra en conflicto con la política del equipo
• Los agentes deben pegar los valores recopilados de nuevo al humano para confirmación antes de comandos destructivos

5. Salidas que Deberías Esperar

Una ejecución de habilidad debe terminar con entregables concretos:

• Sin salida = habilidad fallida - rechaza respuestas de agente que solo resumen documentación
• Las salidas deben hacer referencia a la verificación - go test, govulncheck, golangci-lint run
• Para servicios, incluye siempre go vet ./... cuando los agentes toquen patrones de concurrencia o unsafe

6. Salvaguardas que Toda Habilidad de Go Necesita

Copia estos valores predeterminados en cada SKILL.md:

## Salvaguardas (Go 1.26)
1. Usa `go get` con la política MVS del equipo - nunca `go get -u ./...` a ciegas.
2. Propaga `r.Context()` a todas las E/S salientes (DB, HTTP, gRPC).
3. Devuelve errores tipados; mapea a estado HTTP en una sola capa.
4. Ejecuta `go test -race` cuando la habilidad toque goroutines o estado compartido.
5. Ejecuta `govulncheck ./...` antes de sugerir fusiones de dependencias.
6. No deshabilites reglas de golangci-lint sin excepción de ADR.
7. Los cambios del operador requieren revisión del manifiesto RBAC antes de aplicarlos.

• Las salvaguardas convierten el entusiasmo del agente en disciplina de ingeniería
• Empareja con Mejores prácticas de Habilidades de Agente para reglas en todo el equipo

7. Fijación de Go 1.26 en Habilidades

Los agentes por defecto usan versiones de datos de entrenamiento. Fija explícitamente:

## Fija de pila (requerida)
| Herramienta | Versión |
| --- | --- |
| go | 1.26.x (verificar parche) |
| golangci-lint | configuración del equipo (verificar en la compilación) |
| Enrutador HTTP | stdlib ServeMux (patrones Go 1.22+) |
 
## Específicos de Go 1.26
- GC por defecto Green Tea - perfila antes de asumir que se necesitan ajustes de GOGC.
- Modernizadores `go fix` disponibles - la habilidad no debe luchar contra correcciones automáticas.
- ServeMux soporta `GET /users/{id}` - prefiere stdlib a menos que ADR mande chi/gin.

• Vuelve a fijar las habilidades en cada cambio menor de Go - las habilidades obsoletas son peores que ninguna habilidad
• Comprueba la salida del agente con go test ./... y golangci-lint run

8. Composición de Habilidades (No Dupliques Documentación)

Las habilidades delegán a la documentación humana; no la reemplazan:

## Referencias (leer, no reescribir)
- HTTP: ../net-http/net-http-basics.md
- Contexto: ../context-package/context-basics.md
- Pruebas: ../testing-benchmarking/table-driven-tests-and-subtests.md
- Seguridad: ../security/dependency-scanning-with-govulncheck-and-sbom.md

• Salida de habilidad = plan + comandos + puertas de control
• Salida de documentación = conceptos + casos límite + preguntas frecuentes
• Enlaza en ambas direcciones: las habilidades apuntan a la documentación; la documentación puede decir "invoca la habilidad X para revisión asistida"

9. Verificación de la Salida de Habilidad

Después de cualquier cambio asistido por habilidad:

# Puerta de unidad y de carrera
go test ./...
go test -race ./internal/...
 
# Análisis estático
go vet ./...
golangci-lint run
 
# Seguridad (antes de fusiones de dependencias)
govulncheck ./...

• Trata la salida de habilidad como una PR de ingeniero junior - revisa antes de fusionar
• CI debe ejecutar las mismas puertas de control - ver GitHub Actions para Repositorios Go

10. Prompts de Invocación de Ejemplo

Revisión de manejador net/http:

Usa la habilidad de Revisión de Diseño de API en Go. Pila: Go 1.26, stdlib ServeMux.
Entradas: diff de PR para internal/api/handlers.go adjunto.
Revisa la propagación del contexto, el mapeo de errores y los códigos de estado.
Salvaguardas: sin fusión automática; salida de lista de verificación con referencias de línea.

Auditoría de concurrencia:

Usa la habilidad de Revisión de Concurrencia en Go.
Paquete: ./internal/worker/...
Verifica el ciclo de vida de goroutine, las reglas de cierre de canales y la cancelación del contexto.
Incluye el comando go test -race para los paquetes afectados.

Barrido de seguridad de módulos:

Usa la habilidad de Auditoría de Módulos y Seguridad en Go.
Ejecuta govulncheck ./... y resume las CVEs accionables.
Propón solo fijaciones de go get - el humano aprueba antes de fusionar.

Flujo de trabajo de perfilado:

Usa la habilidad de Perfilado de Rendimiento en Go.
Síntoma: p99 latencia duplicada en /api/orders.
Entradas: pprof de CPU de staging adjunto.
Proporciona pasos de medida-perfilado-optimización; sin micro-optimizaciones prematuras.

Revisión de operador:

Usa la habilidad de Revisión de Operador Kubernetes en Go.
Revisa el diff del reconciliador: finalizadores, referencias de propietario, marcadores RBAC.
Marca cualquier RBAC a nivel de clúster sin aprobación de ADR.

Preguntas frecuentes

Relacionados

• Habilidades de Agente para Equipos de Go - descripción general conceptual
• Habilidad de Revisión de Diseño de API en Go - manual de revisión de manejadores
• Habilidad de Revisión de Concurrencia en Go - auditorías de goroutines
• Habilidad de Auditoría de Módulos y Seguridad en Go - flujo de trabajo de govulncheck
• Habilidad de Pruebas y Benchmarking en Go - andamiaje basado en tablas
• Mejores prácticas de Habilidades de Agente - resumen de 25 puntos para el equipo
• Conceptos básicos de net/http - referencia humana para manejadores

Versiones de pila: Esta página fue escrita para Go 1.26.x (GC Green Tea por defecto, modernizadores go fix - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación). 49454e4f4d5f434e4f5904434556494d43451e1f1f56181a181c1a1d