Escribe y mantén habilidades de gestión de productos que enseñen buen criterio

## Conserva las razones y los ejemplos que enseñan buen criterio al usuario ### Atender a los dos públicos Una habilidad de gestión de productos debe ayudar a quien la practica a completar un trabajo útil y a mejorar en su disciplina. Diseñe cada habilidad tanto para la persona que desarrolla su criterio como para el agente que ejecuta el flujo de trabajo. No optimice para un público a costa del otro. Haga suficientemente visible el razonamiento que sustenta el flujo de trabajo para que las recomendaciones sean fiables, explicables y transferibles. El usuario debe comprender por qué funciona un enfoque, no limitarse a recibir un entregable terminado. ### Proteger la estructura de aprendizaje - No acorte las explicaciones cuando eso elimine el razonamiento necesario para tomar decisiones acertadas. - Conserve los antipatrones explícitos, porque enseñan a los usuarios qué reconocer y evitar en situaciones reales. - Utilice ejemplos que muestren el proceso de razonamiento, no solo el resultado final. - Defina los términos especializados cuando aparezcan por primera vez y haga explícitas las compensaciones. - Mantenga el flujo de trabajo práctico y listo para agentes sin eliminar la capa de acompañamiento. Al mejorar la eficiencia, elimine la repetición, el relleno y los antecedentes secundarios antes que las lecciones, los ejemplos o los modos de fallo. Si no está claro si un pasaje sirve de apoyo o es contenido superfluo, consérvelo hasta comprender su función. ### Demostrar la calidad en distintos contextos Incluya al menos un ejemplo concreto que muestre cómo la evidencia conduce a una decisión. En una habilidad plenamente desarrollada, añada una plantilla reutilizable y ejemplos resueltos de dos contextos empresariales sustancialmente diferentes, como un servicio de software y una empresa física u operativa. Utilice organizaciones y datos ficticios. ## Da a cada habilidad su propia carpeta y no edites a mano las listas generadas ### Separar las fuentes canónicas de los resultados derivados Mantenga cada habilidad en su propia carpeta, nombrada de forma coherente, con un único documento canónico de la habilidad y todos los recursos o scripts de apoyo específicos. Almacene los comandos reutilizables de orquestación por separado de las habilidades individuales. Mantenga la investigación, la documentación para usuarios, las aplicaciones de vista previa y los entregables de publicación en áreas diferenciadas y con una propiedad clara. Trate los catálogos generados, los índices, las copias de paquetes y los paquetes de distribución como artefactos derivados. Vuelva a generarlos desde las fuentes canónicas en lugar de editarlos directamente. Utilice kebab-case en minúsculas para los nombres de las carpetas de habilidades y mantenga sincronizado el nombre de la carpeta con el nombre declarado de la habilidad. Conserve rutas estables siempre que sea posible; cambie el nombre de una habilidad solo cuando sea necesario y, a continuación, actualice todas las referencias. ### Respetar los límites de propiedad Antes de editar el contenido, confirme qué repositorio o espacio de trabajo es su propietario. Una biblioteca compartida, un manual específico de un producto y un repositorio de distribución pueden remitirse entre sí y, a la vez, tener distintas fuentes de referencia. Trabaje en la ubicación propietaria y trate las demás como referencias de solo lectura, salvo que la tarea cambie expresamente ese límite. No deduzca la estructura únicamente a partir de un nombre de directorio conocido. Antes de tomar decisiones estructurales, consulte las definiciones, las reglas de contribución, los scripts y los ejemplos existentes del propio repositorio. ### Encontrar la capacidad más específica Antes de improvisar orientación sobre gestión de productos, examine las habilidades disponibles y elija la coincidencia más específica. Los ámbitos habituales incluyen descubrimiento, Jobs to Be Done, perfiles de usuario, estrategia de producto, priorización, hojas de ruta, documentos de requisitos, historias de usuario, criterios de aceptación, trabajo con productos de inteligencia artificial, flujos de trabajo de agentes y alineación de partes interesadas. Trátelos como flujos de trabajo de acompañamiento y generación de entregables, no como tareas genéricas de ingeniería de software. ## Incluye ejemplos y errores comunes en cada habilidad y pregunta una cosa a la vez ### Utilizar un contrato documental coherente Dé a cada habilidad una secuencia clara, como Propósito, Entrada, Conceptos Clave, Aplicación, Ejemplos, Errores Comunes y Referencias. Incluya en el frontmatter los campos name, description y type. Cuando las plataformas de destino impongan esos límites, mantenga name dentro de 64 caracteres y description dentro de 200 caracteres. Utilice encabezados Markdown claros y párrafos breves. Añada identificadores de lenguaje a los bloques de código delimitados. Mantenga el texto conciso y con una postura definida, pero no sacrifique el razonamiento, las condiciones ni los ejemplos necesarios. ### Convertir la entrada en una invitación, no en una barrera La sección Entrada debe explicar con lenguaje sencillo qué puede proporcionar el usuario e incluir un ejemplo de invocación. Trate la información incluida en la solicitud como respuestas ya proporcionadas. Permita una entrada inicial parcial o inexistente. Explique cómo el flujo guiado recopilará la información que falte en lugar de bloquear al usuario. Evite marcadores de posición específicos de un entorno de ejecución o sintaxis de plantillas que aparezcan literalmente en entornos no compatibles. ### Diseñar deliberadamente los flujos interactivos En una habilidad interactiva: - Haga una pregunta cada vez o utilice grupos pequeños y coherentes. - Deje que cada respuesta determine la siguiente pregunta. - Ofrezca recomendaciones numeradas para los pasos siguientes y adaptadas al contexto. - Permita elegir por número, además de introducir una respuesta personalizada. - Adapte el flujo de trabajo cuando las elecciones del usuario cambien la ruta pertinente. Haga que la habilidad sea autónoma y que un agente pueda utilizarla sin supuestos ocultos. Incluya al menos un antipatrón explícito y explique por qué falla. ## Revisa las habilidades y sus enlaces con las herramientas de la biblioteca antes de compartirlas ### Utilizar la ruta de validación propia de la biblioteca Prefiera las herramientas documentadas del repositorio para el descubrimiento, la validación, el empaquetado y las pruebas de toda la biblioteca antes que las comprobaciones improvisadas. Utilice la detección de archivos y las búsquedas dirigidas de referencias para verificar las ubicaciones de las habilidades y las referencias cruzadas antes de enviar cambios. Valide que las rutas canónicas de las habilidades se resuelvan, que los metadatos sean válidos, que estén presentes las secciones obligatorias, que los ejemplos y las referencias sean correctos y que los enlaces mantengan la coherencia. Cuando no haya pruebas automatizadas, realice estas comprobaciones manualmente en lugar de afirmar un éxito no verificado. Ejecute el generador de paquetes y el generador de catálogos mediante sus puntos de entrada mantenidos. Si se modificó una aplicación de vista previa, utilice la ruta local de vista previa pertinente y verifique su documentación. ### Preservar la compatibilidad y la automatización segura Respete los requisitos de empaquetado específicos de cada plataforma, incluida la coincidencia exacta de mayúsculas y minúsculas en los nombres de archivo cuando sea necesaria. Mantenga los scripts de apoyo deterministas, documentados y sin acceso a la red, salvo que el flujo de trabajo lo exija y lo regule explícitamente. Revise la seguridad de los scripts y del contenido empaquetado antes de compartirlos o ejecutarlos. No elimine archivos gestionados del mercado, de plugins o de compatibilidad solo porque parezcan no estar relacionados. No edite los entregables de publicación generados como sustituto de corregir su fuente canónica. ### Verificar la verdadera fuente de referencia Antes de cambiar una categoría, un tipo de habilidad o una estructura de paquete, fundamente la decisión en los criterios locales y en la habilidad canónica pertinente. Prefiera la evidencia de los validadores mantenidos y las herramientas del repositorio a las convenciones personales. Si el trabajo solicitado pertenece a otro repositorio, detenga la escritura en el límite actual y dirija el cambio a la fuente propietaria. El material de referencia puede servir de base para el trabajo sin convertirse por ello en el objetivo de la edición. ## Haz cambios pequeños y sigue una lista de control antes de publicar ### Preparar contribuciones fáciles de revisar Mantenga los cambios pequeños, mantenibles y limitados al propósito declarado. Utilice asuntos de commit claros y en imperativo. Una solicitud de revisión debe resumir el cambio, enlazar los issues pertinentes, identificar el tipo de habilidad y destacar los cambios significativos de compatibilidad o comportamiento. Al añadir o cambiar el nombre de una habilidad, actualice las entradas de catálogo, los recuentos, las tablas, las rutas y los enlaces cruzados. Antes de la publicación, verifique que todas las referencias se resuelvan. ### Aplicar una lista de comprobación de publicación completa - Valide las carpetas canónicas de habilidades y los metadatos. - Vuelva a crear desde la fuente los paquetes descargables y los catálogos generados. - Confirme que los ejemplos, las referencias y los enlaces de navegación sigan siendo correctos. - Verifique la sintaxis del frontmatter y todas las copias de paquetes específicas de cada plataforma. - Actualice la documentación de la interfaz y las notas de publicación cuando cambie una aplicación de vista previa. - Compruebe que ningún artefacto generado, archivo no relacionado ni sustitución amplia imprevista se haya incorporado al cambio. ### Utilizar los resultados educativos como criterio final Una habilidad lista para publicarse es pedagógica, está preparada para agentes, es autónoma y es práctica. Incluye razonamiento, al menos un ejemplo resuelto, un antipatrón explícito, términos especializados definidos y compensaciones visibles. Una habilidad plenamente desarrollada también incluye una plantilla reutilizable y ejemplos de ámbitos contrastantes. No elimine explicaciones, antipatrones ni ejemplos únicamente para reducir la extensión. Apruebe la publicación solo cuando la habilidad produzca un resultado útil, refuerce el criterio del usuario y siga siendo mantenible en los entornos compatibles.