solidity-security

Visión general de la skill solidity-security

Para qué sirve solidity-security

La skill solidity-security es una guía enfocada de auditoría y codificación segura para smart contracts en Solidity. Resulta especialmente útil cuando quieres que un agente revise la lógica del contrato en busca de clases comunes de explotación, proponga patrones más seguros y explique por qué un diseño es riesgoso antes de que el código llegue a producción o a una auditoría formal.

Quién debería instalar esta skill

Esta skill encaja bien para:

• desarrolladores de Solidity que publican contratos en mainnet o testnets
• auditores que hacen revisiones iniciales
• equipos que preparan contratos DeFi, tokens, vaults o contratos con control administrativo para una Security Audit externa
• ingenieros que quieren una revisión de seguridad más estructurada que un simple prompt de “review this code”

Es menos útil para proyectos no EVM o para análisis puramente económico del protocolo.

La necesidad real que resuelve

Los usuarios no solo quieren una lista de vulnerabilidades. Quieren ayuda para convertir objetivos difusos como “revisa este vault por reentrancy y problemas de privilegios” en un flujo de revisión repetible que cubra rutas de explotación, implementaciones más seguras y prioridades de remediación. Ahí es donde solidity-security ofrece más valor que un prompt genérico.

Qué hace diferente a solidity-security

La skill es específica y práctica. En lugar de dar consejos amplios sobre blockchain, se centra en fallos típicos de Solidity como:

• reentrancy
• casos límite aritméticos
• errores de control de acceso
• llamadas externas inseguras
• patrones de implementación orientados a seguridad

Eso la hace especialmente adecuada cuando importa más la precisión que la amplitud.

Qué conviene saber antes de adoptarla

El repositorio es liviano: el contenido de la skill vive sobre todo en SKILL.md, sin reglas, scripts ni archivos de referencia adicionales. Eso facilita una adopción rápida, pero también significa que la calidad de la salida depende mucho del contexto que aportes. Si solo dices “audit this contract”, lo normal es recibir hallazgos genéricos. Si incluyes propósito del contrato, threat model, roles privilegiados y funciones clave, la solidity-security skill se vuelve mucho más útil.

Cómo usar la skill solidity-security

Cómo instalar solidity-security

Instálala desde el repositorio con tu cliente compatible con skills. Un patrón habitual es:

npx skills add https://github.com/wshobson/agents --skill solidity-security

Si tu plataforma de agentes usa otro mecanismo de instalación, añade la skill desde:

https://github.com/wshobson/agents/tree/main/plugins/blockchain-web3/skills/solidity-security

Qué leer primero en el repositorio

Empieza por:

• plugins/blockchain-web3/skills/solidity-security/SKILL.md

Como esta skill no tiene README.md, rules/ ni references/ de apoyo dentro de su carpeta, SKILL.md funciona como manual operativo completo. Lee primero sus secciones “When to Use This Skill” y las dedicadas a vulnerabilidades para entender el enfoque de revisión que aplica.

Qué entrada necesita la skill para funcionar bien

La calidad de solidity-security usage depende del contexto concreto del contrato. Conviene aportar:

• versión de Solidity
• archivos del contrato o fragmentos clave
• propósito del contrato
• roles de usuario y roles privilegiados
• flujos de activos: quién deposita, retira, mintea, quema, liquida, actualiza
• integraciones externas: oracles, ERC20s, bridges, routers, callbacks
• supuestos sobre actores de confianza
• qué tipo de salida quieres: revisión rápida, checklist de auditoría profunda, escenarios de explotación o remediaciones

Sin eso, la skill solo puede dar una explicación genérica sobre vulnerabilidades.

La mejor forma de plantear un primer prompt de revisión

Un buen prompt inicial sería:

“Use the solidity-security skill to review these contracts for reentrancy, access control, unsafe external calls, arithmetic or accounting mistakes, and other high-severity issues. For each finding, include impact, exploit path, affected functions, and a concrete remediation. Distinguish confirmed issues from areas needing more context.”

Ese prompt funciona porque pide:

• clases concretas de problemas
• salida priorizada
• razonamiento sobre explotación
• recomendaciones de implementación
• manejo explícito de la incertidumbre

Cómo convertir un objetivo vago en un prompt completo

Prompt débil:

• “Check this Solidity code.”

Prompt mejor:

• “Use solidity-security for Security Audit preparation on this vault contract. Focus on withdrawal flow, share accounting, admin powers, pausing, upgradeability assumptions, and external token interactions. Identify critical and high findings first, then list medium-risk hardening opportunities.”

La versión mejor delimita el alcance a superficies críticas para el negocio, lo que mejora la señal y reduce el relleno.

Flujo de trabajo recomendado para auditorías

Un flujo práctico de solidity-security guide sería:

1. Pedir un resumen del threat model a partir del conjunto de contratos.
2. Solicitar un mapa de riesgos función por función.
3. Profundizar en las rutas con llamadas externas que cambian estado.
4. Revisar funciones restringidas por roles y la lógica de inicialización.
5. Pedir ejemplos de remediación para los hallazgos principales.
6. Volver a ejecutar la skill sobre el código corregido y preguntar qué riesgos siguen presentes.

Este flujo por etapas suele dar mejores resultados que pedir una auditoría monolítica en una sola pasada.

Áreas de revisión de alto valor que conviene enfatizar

Al invocar solidity-security, pide explícitamente al agente que se centre en:

• funciones de retiro y pago
• interacciones con tokens que admiten callbacks
• lógica de transferencia de roles y ownership
• rutas de inicialización y upgrade
• invariantes contables
• dependencias de oracles o precios
• controles de emergencia
• supuestos sobre el cumplimiento de ERC20

Son áreas donde los prompts superficiales suelen pasar por alto riesgos relevantes.

Lo que la skill parece cubrir mejor

Por el contenido fuente, la skill destaca sobre todo en clases comunes de vulnerabilidades de Solidity y en patrones de implementación segura, en especial reentrancy y hábitos defensivos relacionados como checks-effects-interactions. Úsala como asistente de revisión y codificación con foco en seguridad, no como sustituto de verificación formal ni de modelado económico a nivel de protocolo.

Consejos prácticos para mejorar la calidad de la salida

Para obtener mejores resultados con solidity-security usage:

• pega las funciones exactas que mueven fondos
• indica qué roles son de confianza y cuáles están bajo control externo
• aclara si los contratos son upgradeable o usan proxy
• pide prerrequisitos de explotación, no solo nombres de bugs
• solicita una clasificación de severidad con justificación
• pide al modelo que separe hechos del código de supuestos

Estos pequeños ajustes mejoran de forma tangible la calidad de decisión.

Qué no deberías esperar de la skill

No esperes que la solidity-security skill haga automáticamente lo siguiente:

• ejecutar tests
• inspeccionar bytecode desplegado
• demostrar invariantes matemáticamente
• sustituir una Security Audit manual completa
• detectar problemas específicos del ecosistema que nunca mencionas

Es más eficaz como estructura de revisión experta sobre el contexto de código y arquitectura que tú le das.

Preguntas frecuentes sobre la skill solidity-security

¿solidity-security sirve para preparar una Security Audit?

Sí. solidity-security for Security Audit es un caso de uso sólido cuando quieres detectar problemas obvios y otros moderadamente sutiles en Solidity antes de pagar una auditoría externa. Ayuda a los equipos a endurecer el código, documentar supuestos y llegar a la auditoría con menos hallazgos evitables.

¿Es mejor que un prompt genérico de “audit my contract”?

Por lo general, sí. Un prompt genérico suele devolver una lista de riesgos de smart contracts bastante estandarizada. La skill solidity-security le da al agente un marco de seguridad más estrecho, lo que normalmente mejora el foco en rutas de explotación, patrones seguros y detalles de remediación.

¿solidity-security es adecuada para principiantes?

Sí, con matices. Los principiantes pueden usarla para aprender superficies de ataque comunes en Solidity y patrones de codificación más seguros. Pero no debería tratarse como un currículo completo. Si estás empezando, pídele a la skill que explique cada hallazgo en lenguaje sencillo y que muestre alternativas seguras.

¿Cuándo encaja mal solidity-security?

Tiene un encaje débil para:

• cadenas no basadas en Solidity
• seguridad de wallets en front-end
• revisión de diseño de tokenomics
• teoría de juegos de gobernanza
• respuesta a incidentes en producción sin contexto de código

Para esos trabajos, conviene usar un proceso de seguridad blockchain más amplio u otra skill especializada.

¿Puede revisar un solo archivo o necesita todo el codebase?

Puede revisar un solo archivo, pero los resultados mejoran con contexto adicional. Por ejemplo, un contrato de vault sin el contexto de su token, oracle, control de acceso o proxy puede parecer seguro cuando los supuestos clave están definidos en otra parte.

¿La skill cubre solo bugs clásicos?

No, aunque los bugs clásicos son su centro de gravedad. Espera su mejor rendimiento en riesgos conocidos de implementación en Solidity, más que en exploits económico-protocolarios a medida. Si tu preocupación principal es insolvencia, manipulación de oracle o diseño de liquidaciones, dilo de forma explícita.

Cómo mejorar la skill solidity-security

Dale a la skill tu threat model desde el principio

La forma más rápida de mejorar la salida de solidity-security es definir:

• capacidades del atacante
• roles de confianza
• activos protegidos
• resultados inaceptables

Ejemplo:

• “Assume any external user is adversarial, admin key is trusted but fallible, and loss of user deposits is the top-risk outcome.”

Esto ayuda al agente a priorizar problemas reales por encima de comentarios de estilo.

Proporciona invariantes, no solo código

Las entradas sólidas incluyen reglas del sistema como:

• el total de shares nunca debería superar los activos reclamables
• solo governance puede cambiar los parámetros de fees
• los retiros de usuarios no deben depender de callbacks no confiables

Cuando aportas invariantes, la skill puede contrastar la lógica con el comportamiento esperado en lugar de limitarse a buscar patrones sintácticos.

Pide narrativas de explotación

Un fallo común es recibir una lista plana de hallazgos sin demostrar por qué importan. Puedes mejorarlo pidiendo:

• condición de entrada
• pasos del ataque
• impacto esperado
• si el problema es realista o solo teórico

Eso obliga a la solidity-security skill a razonar como un auditor, no como un linter.

Haz que las peticiones de remediación sean específicas

No preguntes solo “how to fix this?”. Pide:

• parche mínimo
• alternativa de diseño más segura
• tradeoffs de cada solución
• si el parche cambia los costes de gas o la UX

Los prompts de remediación específicos producen resultados mucho más accionables que un consejo genérico de secure coding.

Vuelve a ejecutarla sobre el código corregido

Después de la primera pasada, pega la función o el contrato revisado y pregunta:

• qué riesgo se eliminó
• qué riesgo residual sigue existiendo
• si la corrección introdujo nuevos casos límite
• qué tests deberían añadirse

Esta es una de las formas de mayor valor para aprovechar bien el tiempo de solidity-security install una vez adoptada.

Errores habituales a vigilar

Incluso con la skill, conviene vigilar:

• exagerar vulnerabilidades especulativas
• pasar por alto supuestos ocultos en contratos heredados
• ignorar detalles de gestión de roles
• dar consejos estándar sobre reentrancy cuando el problema de fondo es el diseño contable
• tratar todas las llamadas externas como igual de peligrosas

Puedes reducir estos errores aportando contexto de herencia y pidiendo al modelo que cite la ruta de función exacta detrás de cada afirmación.

Mejores prompts para revisiones más profundas

Un buen prompt de segunda ronda:

“Use solidity-security to review only the withdrawal, reward-claim, and admin-setter paths. Ignore gas micro-optimizations. For each issue, cite the function, state variable, attacker capability required, exploit sequence, and the safest realistic remediation for this codebase.”

Funciona porque restringe al mismo tiempo el alcance y el formato de salida.

Combina la skill con tests y revisión manual

El mejor flujo no consiste solo en la skill. Usa solidity-security para generar hipótesis y luego valídalas con:

• unit tests
• invariant tests
• fuzzing
• revisión manual línea por línea

Esa combinación es bastante más sólida que limitarse a prompts comunes o a una lectura estática por sí sola.

Cómo evaluar si la skill realmente está ayudando

La solidity-security guide está funcionando si te ayuda a:

• identificar más rápido las funciones más peligrosas
• explicar con claridad la explotabilidad
• producir mejores candidatos de parche
• preparar preguntas más limpias para auditores externos
• reducir la incertidumbre típica de los prompts genéricos

Si la salida sigue siendo vaga después de dos iteraciones, la causa habitual es la falta de contexto del contrato, no la instalación en sí.