¿Qué hace 洁癖.skill – Habilidad de Higiene?
Evita que los agentes AI ensucien tu repositorio con
plan.md,todo.md,summary.mdy artefactos desechables. No dejes que el agente AI convierta la raíz de tu proyecto en un vertedero de Markdown.
Esto no es un eliminador de Markdown. Esta habilidad gobierna el entorno local donde trabajan los agentes: artefactos del repositorio, cachés del espacio de trabajo, almacenamiento WSL2/Docker, cachés de gestores de paquetes, cachés de modelos y estado del agente/IDE.
Un archivo o caché no es basura solo porque sea grande. Se convierte en un riesgo de higiene cuando no tiene intención, no tiene dueño, no tiene lector, no tiene ciclo de vida ni ruta de recuperación. El objetivo no es eliminar agresivamente, sino asegurar que cada artefacto, caché y huella del entorno local tenga un propósito, un lugar y una acción segura a continuación.
1. Modelo de Higiene
Utiliza un modelo de tres capas:
| Capa | Alcance | Ejemplos | Acción por defecto |
|---|---|---|---|
| Repositorio | Artefactos creados por el agente | plan.md, todo.md, .agent_tmp/, .agent_reports/ | clasificar, informar, limpieza en modo simulación (DryRun) |
| Espacio de trabajo | Cachés de desarrollo entre proyectos | node_modules, .venv, target, cachés de compilación | auditar, puntuar, recomendar |
| Máquina local | Cadenas de herramientas y entornos virtualizados | WSL2, Docker Desktop, cachés de paquetes, cachés de modelos, estado del agente/IDE | mapa de solo lectura, cesta de riesgo, guía manual |
Los informes deben separar:
Hallazgos— hechos observados localmente.Sugerencias seguras— próximos pasos de bajo riesgo, como ejecutar una simulación (DryRun) o mover informes futuros a.agent_reports/.Operaciones manuales / riesgosas— migración, compactación de VHDX, reubicación de datos de Docker, reubicación de cachés de modelos o ediciones de configuración. Nunca las realices automáticamente.
2. Cuándo Usar Esta Habilidad
Invoca esta habilidad cuando el usuario pregunte acerca de:
| Disparador | Ejemplos |
|---|---|
| Ordenar / organizar | "ordenar el directorio del proyecto", "limpiar este repo", "organizar mi proyecto" |
| Generar artefactos | "escribir plan", "generar informe", "crear un plan/tarea/resumen/informe/auditoría" |
| Auditar | "auditar archivos del proyecto", "escanear artefactos de agente", "listar archivos sospechosos" |
| Limpiar | "limpiar archivos de agente", "limpiar archivos temporales del agente", "eliminar archivos temporales" |
| Decidir | "¿debería generar este archivo o mantenerlo en el chat?" |
| Puntuar | "poner nota de higiene a mi repositorio", "puntuación de higiene del repo", "¿qué tan limpio está mi repo?" |
| Auditar espacio de trabajo | "escanear espacio de trabajo", "auditar mi espacio de trabajo", "encontrar artefactos de agente en múltiples repos" |
| Auditar entorno local | "auditar mi entorno local", "inspeccionar entorno local del agente", "¿dónde están mis cachés de desarrollo?" |
| Crear reglas | "crear AGENTS.md / CLAUDE.md / Cursor Rules" |
| Finalización de tarea | Verificación de higiene al salir |
| Contaminación | "múltiples agentes escribiendo archivos al azar", "la raíz del proyecto es un desastre de markdown" |
| Queja | "no generes documentos basura", "limpia plan.md / todo.md" |
| Inspección de Entorno | "inspeccionar mi entorno de codificación", "¿dónde está instalado node/python/go?" |
| Crecimiento de Disco | "¿por qué mi disco C está creciendo?", "encontrar cachés de paquetes/modelos" |
| WSL2 / Docker | "WSL2 ocupa demasiado", "el disco de Docker Desktop es enorme", "¿dónde está ext4.vhdx?" |
| Cachés de modelos | "modelos de Ollama/Hugging Face en disco C", "auditoría de caché de modelos AI" |
| Estado del agente | "ubicaciones de estado de Claude/Codex/Cursor", "huella de configuración/caché del agente" |
3. Cuándo NO Usar Esta Habilidad (Nunca Hacer)
Detente y pregunta al usuario o evita estrictamente si la solicitud implica:
- Eliminar documentación formal del proyecto
- Modificar notas escritas por el usuario
- Limpiar código fuente (
src/,lib/,app/) - Tocar directorios de estado de herramientas (
.codex/,.claude/,.cursor/,.vscode/,*.sqlite,state.json,session.json,workspaceStorage,globalStorage,auth-token) - Eliminación masiva no confirmada de Markdown
- Forzar eliminación de archivos bajo control de versiones (Git)
- Limpiar Markdown desconocido en carpetas personales/de usuario
- Modificar configuraciones del sistema o registro
- Registrar tareas programadas
- Subir registros, informes, credenciales o datos del entorno
- Escanear todo el ordenador sin un alcance raíz explícito especificado por el usuario
- Leer tokens de autenticación, archivos de sesión, bases de datos sqlite o registros privados
- Eliminar cachés de herramientas o modelos solo porque son grandes
- Mover herramientas o reescribir variables de entorno sin una solicitud de migración explícita separada
- Compactar archivos VHDX de WSL/Docker
- Exportar/importar distribuciones de WSL
- Editar
.wslconfig, configuraciones de Docker, perfiles de shell o configuración de gestores de paquetes
4. Clasificación de Artefactos
Cada archivo que crea un agente pertenece a una de cinco clases. La clase — no la extensión — determina el tratamiento.
| Clase | Ejemplos | Hogar | Ciclo de vida | ¿Autoeliminar? |
|---|---|---|---|---|
| A — Documentación Formal | README.md, CHANGELOG.md, LICENSE, docs/**, CONTRIBUTING.md, notas de usuario | docs/, raíz del proyecto | Permanente | Nunca |
| B — Entregables Solicitados por el Usuario | informe de auditoría, plan de migración, informe de investigación (el usuario lo pidió explícitamente) | .agent_reports/ | 30 días | Después de la retención |
| C — Artefactos de Trabajo Temporales | plan, tareas, notas, borrador, progreso, lista de tareas | .agent_tmp/ | 7 días | Después de la retención |
| D — Autocomplacientes | resumen, informe_final, resumen_trabajo, lecciones, resumen_cambios | No crear | N/A | N/A |
| E — Estado de Herramienta (fuera de alcance) | .codex/, .claude/, .cursor/, *.sqlite, archivos de estado | Directorios de herramientas | N/A | Nunca |
Reglas clave:
- Clase A → nunca autoeliminar, nunca reescribir automáticamente
- Clase B → nombre de archivo específico
<tarea>_<fecha>.md, nunca en la raíz del proyecto - Clase C → solo
.agent_tmp/, nunca bajo control de versiones, limpiar al final de la tarea - Clase D → no crear. El chat es el resumen.
- Clase E → ignorar completamente, nunca marcar como sospechoso
5. Verificación de Intencionalidad del Artefacto (OBLIGATORIO)
Antes de crear cualquier archivo nuevo, completa esta verificación. Si no puedes responder cada campo, no crees el archivo.
Verificación de Intencionalidad del Artefacto
─────────────────────────────────────────────
1. ¿El usuario solicitó un archivo? sí / no
2. Propósito:
3. Lector:
4. Vida útil esperada: sesión / días / persistente / doc-formal
5. Ruta de destino:
6. Por qué no es suficiente una respuesta en el chat:
7. Clase: temporal / persistente / documentación-formal
8. ¿Debería estar en .gitignore? sí / no
Reglas de decisión:
| Escenario | Acción |
|---|---|
| #1 = no, clase ≠ A | No crear. Responder en el chat. |
| Propósito = plan/tarea/resumen/progreso, lector = este usuario | Solo chat. Sin archivo. |
| Debe crear, clase = C | .agent_tmp/<nombre-específico>.md |
| Debe crear, clase = B | .agent_reports/<tarea_<AAAA-MM-DD>.md |
| Clase = A (doc formal) | Ruta docs/, usuario lo solicitó explícitamente |
| El archivo repite este chat | No crear |
| Sin lector claro | No crear |
| Sin ciclo de vida claro | No crear |
| Sin uso posterior | No crear |
6. Reglas Estrictas para la Generación de Archivos
- Por defecto: no escribir archivos.
- Planes, tareas, resúmenes, progreso → responder en el chat.
- La raíz del proyecto está prohibida para Markdown de proceso genérico a menos que el usuario nombre explícitamente un archivo.
- Prohibido en la raíz del proyecto (a menos que el usuario pida explícitamente ese archivo exacto):
todo.md, plan.md, notes.md, lessons.md, summary.md, report.md, final_report.md, implementation_plan.md, migration_plan.md, audit_report.md, cleanup_report.md, task_list.md, progress.md, work_summary.md, changes_summary.md, *_summary.md, *_report.md, *_plan.md - Archivos temporales →
.agent_tmp/ - Informes persistentes →
.agent_reports/ - Documentos formales →
docs/(solo cuando se solicite explícitamente) - No generes informes para "parecer profesional".
- No crees archivos de resumen automáticos al final de la tarea.
- No dupliques el chat en archivos.
- Usa nombres de archivo específicos:
<tarea>_<contexto>_<fecha>.md - Si el usuario pide un archivo, propón ruta + nombre de archivo primero.
- Si el usuario dice "dime" / "resume" / "planifícalo" → responde en el chat.
7. Ubicaciones Permitidas y Prohibidas
Permitidas
| Contenido | Ubicación permitida |
|---|---|
| Archivos de trabajo temporales | .agent_tmp/ |
| Informes solicitados por el usuario | .agent_reports/ |
| Documentación formal | docs/ (se requiere solicitud explícita) |
| Ruta especificada por el usuario | Cualquier ruta que el usuario haya nombrado explícitamente |
Prohibidas
| Ubicación | Por qué |
|---|---|
| Raíz del proyecto (Markdown de proceso genérico) | Reservada para archivos formales del repo |
src/, lib/, app/ | Directorios de código fuente |
.codex/, .claude/, .cursor/, .vscode/ | Estado de herramienta — no tocar |
8. Archivos Protegidos (Nunca Autoeliminar)
README.md, README.*.md
CHANGELOG.md
LICENSE, LICENSE.*
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
Todo lo que esté bajo docs/
Cualquier archivo bajo control de versiones (Git) fuera de .agent_tmp/ o .agent_reports/
Notas escritas a mano por el usuario
9. Ciclo de Vida
| Ubicación | Retención por defecto | Limpieza |
|---|---|---|
.agent_tmp/ | 7 días | El agente debe limpiar sus propios archivos al final de la tarea |
.agent_reports/ | 30 días | Mover a docs/ para conservación a largo plazo |
docs/ | Permanente | Sin ciclo de vida automático |
10. Puntuación de Higiene del Repositorio
Cuando se solicite una puntuación de higiene del repositorio, prefiere ${CLAUDE_SKILL_DIR}/scripts/score_repo_hygiene.py cuando Python esté disponible. En entornos solo Windows, usa ${CLAUDE_SKILL_DIR}/scripts/score-repo-hygiene.ps1.
| Puntuación | Calificación (es) |
|---|---|
| 90–100 | Limpio |
| 70–89 | Mayormente limpio |
| 50–69 | Necesita orden |
| 0–49 | Vertedero de artefactos |
Dimensiones: limpieza de raíz, colocación de artefactos, claridad de documentos protegidos, higiene de Git, aislamiento de estado del agente, preparación para limpieza. Factores de peso opcionales: --weights references/score-weights.example.json.
Política de proyecto opcional: coloca .tidy-skill.json (o tidy-skill.policy.json) en la raíz del repo, o pasa --policy. Esquema de ejemplo: references/tidy-skill.policy.example.json. La política puede extender patrones raíz prohibidos/protegidos, establecer min_score, requerir .agent_tmp/ + .agent_reports/, y optar por nombres de raíz de planificación intencional mediante planning_root_globs (consulta references/tidy-skill.policy.pwf.example.json para coexistencia con archivos de planificación). .planning/** se reconoce como memoria de trabajo intencional de Clase C sin necesidad de política.
Doctor, reparar, clasificar, instantáneas
| Necesidad | Script |
|---|---|
| Instalación única + doctor de higiene / puerta de CI | ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py |
| Reparaciones seguras con simulación primero (directorios de diseño; movimientos raíz opcionales) | ${CLAUDE_SKILL_DIR}/scripts/tidy_repair.py |
| Emisor de configuración de enlace de host en modo simulación | ${CLAUDE_SKILL_DIR}/scripts/tidy-install-hooks.py |
Clasificar una ruta antes de escribir (Clases A–E); lote mediante --stdin --json | ${CLAUDE_SKILL_DIR}/scripts/classify_artifact.py |
Guardar/comparar historial de puntuaciones; filtrar por min_score | ${CLAUDE_SKILL_DIR}/scripts/hygiene_snapshot.py |
Verbos de seguridad (siempre el mismo significado):
- dryrun — solo vista previa (por defecto para reparación, limpieza, instalar enlaces)
- careful — modifica solo archivos de trabajo del agente (
tidy_repair.py --apply --move-root) - guard — rechaza firmemente configuraciones de host, VHDX, datos de Docker, archivos bajo control de versiones, documentos Clase A
tidy_repair.py es el compañero de diagnóstico→próximo paso del doctor. Por defecto es solo un plan. --apply crea .agent_tmp/ + .agent_reports/ con .gitkeep. Los movimientos de proceso raíz necesitan tanto --apply como --move-root, y aún así rechazan nombres protegidos / bajo control de versiones.
hygiene_snapshot.py save escribe por defecto en .agent_reports/hygiene-history/ (historial de entregables Clase B, no basura en raíz). gate y el doctor salen con código 2 en caso de fallo de higiene/política.
11. Auditoría de Higiene del Espacio de Trabajo
Cuando se solicite escanear múltiples repos, prefiere ${CLAUDE_SKILL_DIR}/scripts/audit_workspace_hygiene.py para una línea base portátil. En flujos de trabajo solo Windows, ${CLAUDE_SKILL_DIR}/scripts/audit-workspace-hygiene.ps1 también es válido. El usuario debe especificar explícitamente un directorio raíz. Nunca escanees discos enteros por defecto.
Para una auditoría de artefactos de agente en un solo repo, prefiere ${CLAUDE_SKILL_DIR}/scripts/audit_agent_artifacts.py cuando Python esté disponible. Usa ${CLAUDE_SKILL_DIR}/scripts/audit-agent-artifacts.ps1 cuando te mantengas en un flujo de trabajo PowerShell. Ambos auditoría y puntuación aceptan --policy opcional.
Verificación opcional de solo lectura al final de la tarea: ${CLAUDE_SKILL_DIR}/hooks/stop-hygiene-check.py (solo informa; nunca elimina). Las frases de activación están en commands/TRIGGERS.md.
12. Auditoría de Higiene de Máquina Local
Cuando se pregunte sobre crecimiento del disco C, WSL2, Docker Desktop, cachés de modelos, cachés de paquetes, estado del agente o expansión del entorno de desarrollo local, usa ${CLAUDE_SKILL_DIR}/scripts/audit-dev-environment.ps1.
Para mapeo portátil de cachés de paquetes/modelos en entornos que no sean Windows, usa ${CLAUDE_SKILL_DIR}/scripts/audit_dev_environment.py. Usa el script PowerShell para inspección específica de Windows de WSL2/Docker VHDX.
Reglas:
- Pide raíces de escaneo explícitas cuando se necesite escanear proyectos/espacios de trabajo.
- Usa
-IncludeUserProfilesolo cuando el usuario quiera incluir ubicaciones de caché del perfil de usuario por defecto. - Usa
-IncludeDrivessolo cuando el usuario pida explícitamente pistas a nivel de disco. - Trata la migración de WSL/Docker, compactación de VHDX, reubicación de datos de Docker, ediciones de
.wslconfigy reubicación de cachés de modelos comoOperaciones Manuales / Riesgosas. - Nunca leas tokens, archivos de sesión, bases de datos SQLite, claves de registro, registros privados o almacenes de credenciales.
Para detalles de WSL2 y Docker, lee references/wsl2-docker-hygiene.md.
13. Reglas de Limpieza
Limpieza automática permitida:
.agent_tmp/— archivos con más de 7 días.agent_reports/— archivos con más de 30 días- Directorio temporal de agente especificado por el usuario
- Archivos de proceso nombrados, caducados, creados por el agente
Limpieza automática prohibida:
- Documentos protegidos (Clase A)
- Código fuente
- Estado de herramienta (Clase E)
- Markdown desconocido en carpetas de usuario
- Archivos bajo control de versiones (Git)
- Archivos sospechosos a nivel de raíz → solo informar, preguntar al usuario
14. Reglas de Auditoría
- Solo lectura — nunca modifica archivos
- Profundidad limitada, omite
.git/,node_modules/,dist/,build/,target/,.venv/,venv/ - Lista:
.agent_tmp/,.agent_reports/, archivos sospechosos a nivel de raíz, documentos protegidos - Sugiere acciones, no realiza ninguna
- Sin subidas ni llamadas de red
15. Lista de Verificación al Final de la Tarea
Antes de informar "hecho":
- ¿Creé algún archivo? ¿Se justificó cada uno mediante una Verificación de Intencionalidad del Artefacto?
- ¿Están todos los archivos temporales en
.agent_tmp/? - ¿Están todos los informes solicitados en
.agent_reports/con nombres con fecha? - ¿Hay algún archivo en la raíz del proyecto que debería estar en
.agent_tmp/? - ¿Hay algún archivo Clase D (autocomplaciente) creado? Si es así, eliminarlo.
- ¿Se ha ejecutado la comprobación de solo lectura al final de la tarea (si está configurada)?
- ¿Se ha respondido al usuario con un resumen en el chat? (Ningún archivo de resumen)
Esta habilidad promueve un espacio de trabajo limpio e intencional para el desarrollo asistido por AI.