Crea skills y plugins de agente que se cargan y se activan correctamente

## Lee la documentación oficial y adapta un skill de referencia Antes de escribir nada, lee la documentación oficial vigente del sistema de plugins y skills al que te diriges: el formato de plugin, el formato de skill y las buenas prácticas de creación publicadas. La documentación del proveedor cambia más rápido que cualquier artículo de terceros, así que trátala como la fuente de verdad y trata las guías de la comunidad como comentarios añadidos sobre ella. Después elige una skill de referencia del nivel de complejidad que necesites y adáptala en lugar de diseñar una estructura desde cero: - Básica: frontmatter mínimo y un bloque breve de orientación, nada más. - Intermedia: un paquete de lenguaje, un directorio de referencias y documentos específicos de cada idioma. - Avanzada: scripts, archivos de flujo de trabajo, plantillas, utilidades de extracción y varios puntos de entrada. Leer dos o tres plugins en producción de otros equipos suele ser más rápido que inventar una estructura. Si el entorno ofrece un agente auxiliar que conoce la documentación para preguntas sobre plugins y skills, dirige esas preguntas allí en lugar de responder de memoria. ## Mantén una sola fuente de metadatos aunque varios runtimes carguen el plugin Cuando más de un runtime de agente puede cargar tu plugin, elige un único formato de metadatos como canónico y no añadas copias paralelas específicas de cada runtime. Los metadatos duplicados se desincronizan, y esa desincronización la descubren los usuarios en lugar de la integración continua. En la práctica: - Mantén el manifiesto del marketplace y el manifiesto de cada plugin en su única ubicación canónica. - No crees directorios de manifiestos ni directorios de metadatos de plugin paralelos y específicos de un segundo runtime. - Mantén todos los componentes en la raíz del plugin usando las rutas por defecto que ambos runtimes ya entienden: el directorio de skills, el archivo de hooks, el archivo de configuración de MCP y el archivo de configuración de la aplicación. - Si un plugin necesita configuración de MCP, colócala en el archivo de configuración de MCP dedicado en la raíz del plugin, en lugar de incrustar un objeto dentro del manifiesto del plugin. Ejecuta la comprobación de carga para cada runtime compatible antes de enviar. Cuando un runtime falle, corrige la fuente canónica para que el otro runtime pueda cargarla mediante la capa de compatibilidad — nunca añadiendo una segunda copia de los mismos metadatos. ## Coloca los directorios de componentes en la raíz del plugin, no en el de metadatos Un directorio de plugin contiene un directorio de metadatos del plugin que incluye únicamente el manifiesto del plugin (nombre, versión, descripción, autor), además de directorios opcionales para comandos de barra, agentes autónomos, skills y hooks de eventos, más un README que documente el plugin. Cada skill vive en su propio directorio dentro del directorio de skills, con un documento de punto de entrada que lleva el frontmatter, y subdirectorios opcionales para referencias, flujos de trabajo y scripts. La regla con la que más gente tropieza: los directorios de componentes — skills, comandos, agentes y hooks — deben estar en la raíz del plugin, no dentro del directorio de metadatos del plugin. Allí solo corresponde el manifiesto del plugin. Tanto los cargadores como los revisores dependen de esto, y un directorio de componentes mal ubicado se manifiesta normalmente como un plugin que, en silencio, no expone nada. ## Elige un nombre claro en kebab-case y completa el frontmatter El frontmatter del punto de entrada de una skill necesita, como mínimo, un nombre y una descripción. Una lista opcional de herramientas permitidas restringe la skill a las herramientas que realmente necesita, algo que vale la pena configurar siempre que la skill sea acotada. - El nombre va en kebab-case y se mantiene dentro del límite de longitud, habitualmente 64 caracteres. - La descripción se escribe en tercera persona e indica tanto qué hace la skill como cuándo usarla. - Prefiere la forma en gerundio para los nombres: un nombre que empiece por verbo, como "analyzing-contracts" o "processing-pdfs", se lee mejor que un nombre de agente sustantivado como "contract-analyzer" o "pdf-processor". - Evita nombres vagos como helper, utils, tools o misc, que coinciden con todo y no significan nada. - Evita palabras reservadas, incluidos nombres de proveedores y de productos, que el runtime puede tratar de forma especial. ## Escribe en la descripción qué hace el skill y cuándo usarlo Tu skill compite con otras cien por la atención, y la descripción suele ser el único texto que el agente lee al decidir si la carga. Una descripción vaga hace que la skill quede sin usarse o, peor aún, que se dispare en la situación equivocada. - Voz en tercera persona: "Analiza X", no "Yo ayudo con X". - Incluye la situación que la activa, no solo el tema: "Úsala al auditar contratos inteligentes" aporta muchísima más señal de enrutamiento que "Herramienta de contratos inteligentes". - Sé específico sobre la capacidad: "Detecta vulnerabilidades de reentrada" supera a "Ayuda con la seguridad". Escribe la descripción como si fuera la regla de enrutamiento que en realidad es, y reléela preguntándote si una skill competidora ganaría esa misma solicitud. ## Evita rutas absolutas y declara las dependencias dentro del script Nunca codifiques rutas absolutas de forma fija. Usa la variable de directorio base que proporciona el runtime, y usa barras inclinadas incluso en Windows, para que la misma skill funcione en cualquier máquina. Cuando una skill incluye scripts que tienen dependencias: 1. Declara las dependencias en línea en la cabecera del script usando el bloque estándar de metadatos en línea de ese lenguaje, incluida la versión mínima del lenguaje. Esto permite que el ejecutor resuelva todo sin un paso de instalación aparte. 2. Invoca el script a través de un ejecutor que respete esos metadatos en línea, de modo que la resolución de dependencias sea automática en lugar de un requisito previo documentado. 3. Mantén un archivo de proyecto en el directorio de scripts para el instrumental de desarrollo, como linters y formateadores. 4. Documenta las dependencias a nivel de sistema que el gestor de paquetes del lenguaje no puede instalar — el instrumental de PDF y OCR, por ejemplo — en los archivos de flujo de trabajo, con comandos de instalación específicos para cada plataforma. ## Mantén rápidos los hooks que se ejecutan antes de cada comando Los hooks que se ejecutan antes de cada comando están en la ruta caliente, así que su coste se paga en cada invocación. Aquí el rendimiento es una cuestión de corrección, no un lujo. - Prefiere un shell más un filtro JSON ligero antes que un intérprete completo. El arranque del intérprete y del analizador añade una latencia que los usuarios notan en cada comando. - Falla rápido y pronto: sal con éxito e inmediatamente ante comandos que claramente no coinciden, de modo que la abrumadora mayoría de las invocaciones resulten prácticamente gratuitas. - Favorece las expresiones regulares frente al análisis completo del árbol sintáctico. Acepta falsos positivos poco frecuentes cuando la mejora de rendimiento sea significativa y el agente simplemente pueda reformular el comando. - Anticipa las formas de los falsos positivos: los comandos de diagnóstico que solo localizan un intérprete, los comandos de búsqueda que mencionan su nombre como término de búsqueda y los nombres de archivo que contienen ese nombre no deben activar la interceptación. - Documenta estos compromisos en la descripción del cambio, para que los revisores vean que las decisiones fueron deliberadas y no descuidadas. ## Enseña cuándo y por qué consultar en vez de pegar especificaciones enteras Una skill debe aportar orientación que el modelo aún no tiene. Pegar una especificación entera dentro de una skill consume contexto y no añade nada que el modelo no pudiera consultar por su cuenta. - No pegues especificaciones completas ni referencias de API. Enseña en cambio cuándo y cómo buscar la información. - Explica el porqué, no solo el qué: incluye compensaciones, criterios de decisión y las decisiones de criterio que alguien novato resolvería mal. - Documenta los antipatrones junto con la razón por la que están mal, en lugar de una lista escueta de prohibiciones. Un buen ejemplo del patrón: una skill para un formato binario complejo de depuración no incrusta la especificación del formato. Enseña a qué herramientas de inspección recurrir, cómo consultarlas y qué herramienta es la adecuada para cada pregunta. ## Ajusta la rigidez al riesgo de la tarea y di cuándo no usar el skill Cuán rígida debe ser una skill depende de lo frágil que sea la tarea. - Estricta para tareas frágiles: las auditorías de seguridad, las implementaciones criptográficas y las comprobaciones de cumplimiento necesitan procedimientos rígidos, aplicados y paso a paso. - Flexible para tareas variables: la exploración de código, la documentación y la refactorización deben ofrecer opciones y dejar margen para el criterio. Todo punto de entrada de una skill debe incluir dos secciones. Una sección "Cuándo usarla" que enumere los escenarios concretos en los que la skill aplica, y una sección "Cuándo NO usarla" que nombre los casos en los que otro enfoque es mejor. La sección negativa es la que la gente se salta, y es la que impide que la skill se dispare en el lugar equivocado. Las skills de auditoría y de seguridad necesitan una tercera sección, "Racionalizaciones que rechazar", que enumere los atajos y las excusas habituales que llevan a pasar por alto hallazgos — porque bajo presión de tiempo esas racionalizaciones son exactamente las que aparecen. ## Mantén corto el archivo principal y enlaza los detalles a un solo nivel Mantén el punto de entrada de la skill por debajo de unas 500 líneas y reparte el resto en un directorio de referencias y un directorio de flujos de trabajo. Pon primero el inicio rápido y deja los detalles detrás de enlaces, de modo que quien solo necesita la ruta habitual nunca cargue lo demás. Mantén los enlaces a un solo nivel de profundidad: el punto de entrada enlaza a archivos, y esos archivos no encadenan enlaces hacia más archivos. La profundidad de directorios en sí no es problema — un directorio de referencias con subcarpetas por tema es perfectamente razonable. El problema es la indirección encadenada, no las carpetas anidadas. Una forma típica es una sección de inicio rápido con las instrucciones esenciales, una sección de uso avanzado que apunte a un documento de referencia con patrones detallados, y una sección de referencia de la API que apunte a otro con la documentación completa de los métodos. ## Supera las comprobaciones automáticas y humanas y sube la versión antes de la revisión Separa lo que valida la automatización de lo que debe juzgar una persona revisora, y resuelve ambas cosas antes de abrir una revisión. Comprobaciones automáticas: frontmatter válido con nombre y descripción; un nombre en kebab-case dentro del límite de longitud; que todos los archivos referenciados existan realmente; que no haya rutas fijas al directorio personal; que la comprobación de carga pase en cada runtime compatible. Comprobaciones de quien revisa: que la descripción se active correctamente y esté escrita en tercera persona; que estén presentes tanto la sección "Cuándo usarla" como la sección "Cuándo NO usarla"; que los ejemplos sean concretos, mostrando la entrada y la salida resultante; que el documento explique el porqué y no solo el qué. Documentación: que el plugin tenga un README; que esté añadido a la tabla del README raíz; que esté registrado en el manifiesto del marketplace a nivel de repositorio y no en el propio directorio de metadatos del plugin; y que una entrada de propiedad nombre a las personas responsables en el archivo de propietarios de código. Actualizaciones de versión de un plugin existente: incrementa la versión tanto en el manifiesto del plugin como en la entrada del marketplace a nivel de repositorio, y mantén los dos números idénticos. Muchos clientes descargan una actualización solo cuando el número de versión aumenta, así que un incremento olvidado significa que nadie recibe la corrección.