CaseYwY/skills

manage-project-skills — selección y auditoría de habilidades del proyecto

0. Jerarquía de reglas (leer primero)

1. Autorización (máxima prioridad, sin excepciones): no instalar/actualizar/eliminar, no escribir archivos del proyecto sin aprobación explícita del usuario; excepción: escrituras aprobadas en el libro de contabilidad. aprobación = habilidad específica + fuente + alcance; "gestiona mis habilidades" no autoriza nada individual.
2. Proceso: seguir el modo seleccionado (T0/T1/T2/auditoría); los pasos "prohibidos" nunca se omiten por eficiencia.
3. Orientación: local primero, moderación — se permiten desviaciones con una razón explícita.

Central: falta es mejor que mal instalado — retroceder ≈ 1 min; instalación incorrecta = contexto permanente + competencia de disparadores. moderación, justificación obligatoria, local primero.

1. Modos

Requisitos poco claros ⇒ necesidades totales incognoscibles ⇒ sin instalación masiva al inicio.

• T0 · inventario inicial (SOLO LECTURA): pasos 1-2 + informe en chat ("cubierto / no instalando"). cero instalaciones/escrituras. inicialización del libro de contabilidad = escritura aprobada separada. matriz de cobertura = solo necesidades deducibles de la pila. ruta rápida: libro de contabilidad existe && sin mención de habilidades ⇒ solo leer libro de contabilidad. reinventariar si: directorios de skills / AGENTS.md / lockfile / agente cambiaron ∨ libro de contabilidad ≠ disco ∨ usuario lo solicita.
• T1 · por brecha (durante la tarea): clasificar primero. respuesta única (detalle de API, comando individual) ⇒ buscar, no instalar. reutilizable (flujos de trabajo/estándares/cadenas de herramientas que este repositorio vuelve a usar) ⇒ extraer una habilidad ⇒ registrar. la entrada se basa en reglas de AGENTS.md (ver MAINTENANCE.md), no en autoevaluación del modelo.
• T2 · plan definido: instalación por lotes, cada candidato justificado por el plan confirmado. pasos completos 1-7.
• Auditoría: usuario solicita revisión/limpieza/limpieza ⇒ ver final.

Todos los modos comparten el libro de contabilidad del proyecto .agents/skills-rationale.md (si está aprobado); leerlo primero.

2. Flujo

1. Perfilar el proyecto

Leer si está presente (no adivinar): manifiestos (package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj); diseño + señales de monorepo (workspaces, turbo.json); infraestructura (.github/workflows, Dockerfile, vercel.json, wrangler.toml); encabezado README, docs/agents/.

2. Inventariar cobertura (local primero; deduplicar antes de extraer)

Orden: instalado en proyecto → global → registro. Dos clases:

• habilidades personales: globales, transversales a proyectos. no duplicar en el proyecto; registrar agente destino. presencia global ≠ dependencia declarada del proyecto.
• críticas para el proyecto: el flujo de trabajo/entrega depende de ellas. registrar fuente + versión/commit + ruta de restauración — incluso si están instaladas globalmente; las máquinas nuevas no heredan globales.

Escanear: directorios del proyecto (.agents/skills, .opencode/skills, .claude/skills = ejemplos comunes, confirmar según documentación del agente; inalcanzable ⇒ "no verificado", nunca "sin skills"); global mediante npx skills ls -g; manifiesto fuente y skills-lock.json (sincronizar si está presente). Salida: matriz de cobertura (necesidad → satisfecha por / brecha).

3. Llenar brechas desde fuentes confiables

Niveles de confianza: oficial del proveedor (anthropics/skills, openai/skills, supabase/agent-skills) > autor original (mattpocock/skills, cursor/plugins) > comunidad > no verificable (elevar escrutinio). si no, npx skills find <kw> — el número de instalaciones es referencia, no confianza. nada encaja ⇒ decirlo + proponer skill-creator; sin soluciones aproximadas.

4. Presupuesto: sin límite estricto, basado en necesidades

• cada candidato necesita una razón concreta ("el proyecto tiene X ⇒ Y"); sin razón ⇒ descartar.

• ~10 candidatos = error de análisis ⇒ re-auditar pasos 1-2.

• marginal ⇒ lista "diferida" (retroceder es barato).
• deduplicar ≠ poda automática: superposición de descripciones ⇒ agrupar candidatos ⇒ comparar disparadores/E-S/efectos secundarios/deps/versiones ⇒ fusionar/eliminar solo con evidencia de reemplazo + aprobación del usuario; si no, mantener ambos, marcar "a comparar".

5. Puerta de seguridad: antes de instalar, aprobación del usuario

Revisar el paquete completo, no solo SKILL.md:

1. leer SKILL.md completamente + todos los archivos/scripts/configuraciones/deps referenciados; por cada script verificar: ejecución / red / escrituras / credenciales.
2. registrar evidencia de escaneo: escáner + veredicto + versión coincidente + fecha. sin escaneo = desconocido, no seguro. desacuerdo entre escáneres ⇒ listar, no promediar.
3. fuente privada sin escaneos ⇒ revisión manual de archivos completa reemplaza la puerta, marcada "sin escanear".
4. riesgo medio+ o comportamiento inexplicado ⇒ usuario decide; nada se instala mientras no esté claro.

6. Instalar

# detecta automáticamente el agente (informar la detección al usuario); máquinas multi-agente: pasar --agent
npx skills add <owner/repo>@<skill> --copy -y

• canal 2 — versión fija / resguardo npm inalcanzable: gh skill install <owner/repo> <skill[@version]> --agent opencode (vista previa; copia archivos, no actualiza skills-lock ⇒ el libro de contabilidad registra fuente+versión; siempre pasar --agent — el valor predeterminado no interactivo es github-copilot). un canal por habilidad — no mezclar.
• --copy = aislamiento instantáneo, NO fijación de versión: sin sincronización ascendente, sin identidad de versión, reinstalar lo cambia. reproducibilidad ⇒ libro de contabilidad registra: fuente + ruta + versión/commit (+hash).
• habilidades críticas para el flujo de trabajo del proyecto: --copy, nunca enlace simbólico (el enlace simbólico sigue la fuente ascendente).
• skills-lock.json generado ⇒ commit (restaurar: npx skills experimental_install); asegurar que .agents/ no esté en .gitignore.
• efectividad varía: OpenCode recarga en caliente (verificado); otros agentes pueden necesitar reinicio ⇒ pedir al usuario reiniciar + re-verificar.
• GitHub inalcanzable ⇒ informar + proponer caché local; nunca omitir en silencio.

7. Verificar y registrar (cuatro capas; capa faltante = "no verificado")

• archivo: existe, ruta correcta, referencias completas
• manifiesto: npx skills ls coincide con lockfile y disco (visible ≠ cargable)
• carga: el agente destino realmente carga la habilidad
• comportamiento: una tarea positiva representativa funciona
• escribir decisiones (qué/por qué/diferido/verificado-hasta) → .agents/skills-rationale.md
• eliminar: preferir npx skills remove <name> -y (parámetros según npx skills --help); nunca solo eliminar el directorio (desincronización del lockfile); registrar fuente+versión antes de eliminar; hacer copia de seguridad si no es recuperable; verificar las cuatro capas después.

3. Modo auditoría

Incluye esta misma habilidad. informe → aprobación del usuario → ejecutar. comprobaciones:

1. duplicados: agrupar descripciones ⇒ grupos candidatos ⇒ comparar disparadores/E-S/efectos secundarios/deps/versiones; evidencia de reemplazo + aprobación ⇒ fusionar/eliminar; si no, mantener ambos (a comparar). nunca eliminar por similitud.
2. conflictos: contradicciones en el mismo escenario ⇒ registrar citas + alcance ⇒ usuario decide.
3. inflación: sin telemetría de uso — "nunca disparado" = proporcionado por el usuario. medible: descripción inflada vs función, superposición con habilidades de mayor frecuencia. degradar ⇒ ruta de restauración del estado.
4. referencias muertas: entrada requerida (faltante = bloqueante) / dependencia opcional (ausente = saltar) / salida esperada (creada en tiempo de ejecución; ausencia ≠ error). referencia muerta ⇔ entrada requerida faltante + sin recuperación. informe: evidencia → recomendación → impacto → autorización. antes de eliminar: confirmar recuperabilidad (npx skills find); no recuperable ⇒ hacer copia de seguridad + preguntar. hallazgos → libro de contabilidad.

4. Mantenimiento y aplicación

Plantillas de reglas AGENTS.md, bucle de diagnóstico de fallos de disparadores, conjunto de pruebas de 15 escenarios, flujo de lanzamiento → MAINTENANCE.md — ejecutar antes/después de editar esta habilidad.