hackycy/init-agents-md

Inicializar AGENTS.md

Crea una guía de contribución para la raíz del repositorio o para un directorio existente. El formato de salida y las secciones recomendadas provienen únicamente de references/agents-md-prompt.md; este skill se encarga de aplicar las instrucciones fijas de forma segura al ámbito correcto.

Entrada y Ámbito

• Acepta cero o un argumento de directorio; las rutas relativas se resuelven respecto al directorio de trabajo actual. Sin argumento, usa la raíz de Git encontrada con git rev-parse --show-toplevel.
• Un directorio explícito puede estar fuera de un repositorio Git; si no se proporciona argumento y no se encuentra raíz de Git, pide al usuario que especifique un directorio y se detiene. La ruta debe resolverse a un directorio legible; rutas faltantes, archivos, directorios no legibles o múltiples argumentos de directorio provocan la detención.
• El candidato de salida por defecto es AGENTS.md en ese directorio. Solo se procesa un ámbito a la vez; no se crean directorios, no se modifican otros archivos, no se hace stage, commit ni se crean ramas.
• El cuerpo sigue el idioma principal de la documentación local; si la señal es insuficiente, se usa inglés. Si el directorio seleccionado no es la raíz del repositorio, se añade al inicio una sección ## Scope que indica el directorio relativo y las guías padre aplicables, escribiendo solo reglas nuevas o más restrictivas.

Primero Reconocer, Luego Generar

1. Antes de redactar, lee el destino y el contexto necesario del proyecto: estructura de directorios, manifiestos/lockfiles, scripts, configuración de build/test/lint, CI, README/CONTRIBUTING y, si Git está disponible, hasta 30 commits relevantes. Identifica los límites de paquetes en monorepos, el gestor de paquetes y el idioma principal de la documentación local.
2. Encuentra todos los AGENTS.md relevantes: el archivo destino, los archivos ancestros desde la raíz del repositorio hasta el directorio padre del destino, y los archivos anidados en el subárbol del destino. Para directorios fuera de Git, comprueba la cadena de ancestros. El subárbol se inspecciona primero en subdirectorios inmediatos, y solo se expande si los manifiestos, límites de paquetes o guías existentes apuntan a niveles más profundos; se omiten .git, dependencias/vendor, salidas de build/coverage, cachés y almacenes de secretos ignorados.
3. Etiqueta las coincidencias como target, ancestor o nested, y lee CLAUDE.md, CONTRIBUTING.md y otras guías relevantes como restricciones. Las guías anidadas solo se leen, conservan y enlazan si es necesario; no se fusionan ni modifican.
4. Solo se inspeccionan nombres y metadatos de archivos potencialmente secretos. Nunca se leen ni escriben claves, tokens, credenciales ni contenido de .env.
5. Cada comando y convención debe poder ser verificado mediante scripts, configuración, archivos existentes o historial. Distingue las reglas observadas en el repositorio de las sugerencias genéricas por defecto; las secciones, comandos o afirmaciones sin evidencia se omiten directamente.

Confirmación de Guías Coincidentes

Antes de generar un borrador, muestra todas las coincidencias, sus respectivos ámbitos y la ruta de salida candidata, y comprueba conflictos de mayúsculas/minúsculas (por ejemplo agents.md). Este es un punto de control obligatorio:

• Si el candidato destino ya existe, léelo y pide al usuario que elija entre merge, replace o abort.
• Si el destino no existe pero se encuentran guías ancestro o anidadas, pide al usuario que elija explícitamente "crear una nueva guía para este ámbito" o "actualizar una guía existente con nombre"; no se añaden archivos hijo en silencio. Si se elige otro archivo existente, se vuelve a reconocer el directorio de ese archivo antes de elegir el modo.
• Si no hay coincidencias, continúa redactando un nuevo archivo para el destino original.
• Si el AGENTS.md seleccionado es un enlace simbólico, directorio, archivo especial o archivo normal no escribible, se detiene y se informa el motivo.

Cualquier pregunta sin respuesta, elección ambigua o conflicto con guías como CLAUDE.md deja el espacio de trabajo sin cambios.

Leer las Instrucciones Fijas

Antes de empezar a redactar, lee completamente references/agents-md-prompt.md. Es el propietario canónico del título, requisitos de documentación, secciones recomendadas, objetivo de palabras y estilo de expresión; no lo modifies durante la ejecución normal, ni copies su contenido en este skill.

Fusionar, Previsualizar y Escribir

merge fusiona según la semántica de los encabezados Markdown: conserva los hechos existentes y las secciones personalizadas, solo añade contenido faltante respaldado por evidencia. Presenta todos los conflictos de comandos, rutas, prioridades o hechos en una tabla para que el usuario elija elemento por elemento entre conservar lo existente, adoptar la evidencia o proporcionar texto personalizado; no se escribe mientras haya conflictos sin resolver. replace afecta solo al archivo seleccionado, sin crear copia de seguridad automática.

Para archivos nuevos, muestra el borrador completo; para actualizaciones, muestra un diff unificado, acompañado de un resumen de ruta, ámbito, secciones, número de palabras, lagunas de evidencia y modo. No se crea ni modifica ningún archivo hasta que el usuario confirme explícitamente la escritura final; si solicita cambios, se vuelve a redactar y previsualizar. Antes de escribir, relee el destino; si el contenido ha sido modificado externamente, se reinicia el proceso de confirmación.

Validación y Finalización

Antes de escribir, comprueba títulos, jerarquía de encabezados, enlaces de ámbito en guías anidadas, rutas/scripts referenciados, marcadores de posición, valores sensibles y espacios en blanco Markdown; las guías raíz se verifican contra el objetivo de palabras de las instrucciones fijas, las anidadas incrementales se verifican aproximadamente entre 100 y 300 palabras. Solo se corrigen automáticamente problemas mecánicos como espacios finales o líneas en blanco duplicadas, y se vuelve a previsualizar; los problemas semánticos o fácticos se dejan a decisión del usuario. Si el destino está en Git, ejecuta git diff --check; de lo contrario, realiza una comprobación de espacios en blanco equivalente; no ejecutes build, test o lint completos por defecto para este skill.

Condiciones de finalización: el AGENTS.md confirmado existe en la ruta seleccionada, pasa las comprobaciones estáticas y coincide con la previsualización aprobada; informe final del modo, ámbito, comandos verificados, elementos omitidos/inciertos y resultado de la validación. Si el usuario elige abort o la validación falla, informa el motivo y deja el destino sin cambios.