Gotchas

Skills no aparecen en Claude Code

Los skills necesitan estar en ~/.claude/skills/ para que Claude Code los detecte. La cadena de symlinks es:

~/.claude/skills/{name} → ../../.agents/skills/{name} → ~/Projects/github/llm-toolkit/skills/{name}

Si un skill no aparece, verificar que ambos symlinks existan y apunten correctamente.

Naming: directorio del repo ≠ nombre de deployment

El directorio en el repo puede tener un nombre distinto al name en SKILL.md. Ejemplo: skills/github-actions/ tiene name: github-actions en SKILL.md, pero el symlink puede llamarse distinto.

Siempre verificar que el name en SKILL.md coincida con el nombre del symlink en ~/.agents/skills/ y el entry en .skill-lock.json.

allowed-tools siempre incluir en frontmatter

Sin allowed-tools en el frontmatter del SKILL.md, el skill no tiene permisos para usar herramientas. Agregar siempre los tools mínimos necesarios:

---
name: mi-skill
description: ...
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

No copiar archivos de skills a ~/.agents/skills/. Usar symlinks al repo para que los cambios se reflejen inmediatamente sin re-copiar.

Si se instaló un skill con claude skill install, la copia estática en ~/.agents/skills/ no se actualiza al editar el repo. Borrar la copia y crear symlink.

CABA: código de entrada tiene 8 dígitos

El formato del código de entrada del RPI es E{8 dígitos}{letra trámite}{4 año}. Ej: E00213456I2026. Si se anota con 7 dígitos en vez de 8, al verificar el trámite devuelve el informe de otra persona. Siempre validar que el número tenga 8 dígitos entre la E y la letra de trámite.

CABA: “Salido Definitivo” no significa descargable

Al verificar un trámite en el RPI, el estado “Salido Definitivo” no significa que se puede descargar inmediatamente. El sistema indica una fecha posterior (ej: “Ud. podrá descargar la solicitud a partir del día 19/03/2026”). Para Informe N°3 trámite Común, son 2 días hábiles sin contar el día de presentación.

LM Studio: backend MLX roto (libpython3.11)

El backend MLX de LM Studio (v1.4.0) no puede cargar modelos safetensors porque falta cpython3.11-mac-arm64@10 en ~/.lmstudio/extensions/backends/vendor/_amphibian/. El botón “Fix” en Settings descarga algo pero no persiste.

Workaround: Usar mlx-vlm (pip3 install mlx-vlm) para correr modelos MLX directamente sin LM Studio. Los modelos GGUF funcionan normal con el backend llama.cpp.

Issue: https://github.com/lmstudio-ai/lmstudio-bug-tracker/issues/1645

Qwen3.5-35B-A3B MLX no funciona para vision

La versión MLX (mlx-community/Qwen3.5-35B-A3B-4bit) falla con mlx-vlm y vmlx para tareas de vision. Error: Qwen3VLVideoProcessor requires the PyTorch library. El procesador de transformers v5 importa un video processor que depende de PyTorch. Hacer downgrade a transformers<5.0.0 tampoco lo arregla.

Workaround: Usar la versión GGUF via LM Studio (--backend lmstudio), o usar Qwen3-VL-30B-A3B (MLX) que sí funciona con mlx-vlm.

No descargar mlx-community/Qwen3.5-35B-A3B-4bit para vision — son 20 GB desperdiciados.

ffmpeg scdet: threshold bajo no detecta animaciones CSS suaves

scdet con threshold 3-8 puede detectar 0 cambios en animaciones CSS suaves (opacity, transforms) donde la diferencia entre frames es gradual. Scores típicos <3 para este tipo de contenido.

Workaround: Para videos cortos (≤30 frames), analyze-frames.sh manda todos los frames al modelo sin filtrar. Para videos largos con 0 detecciones, bajar --threshold o usar tblend que siempre genera diffs.

GIFs con Bayer dithering: false positives en scene detect

GIFs de Gifox (u otros con Bayer dithering, paleta de 192 colores) generan ruido entre frames que scdet interpreta como cambios. Subir --threshold a 12-14.

debug-frames/ se acumula

Cada corrida del video-debugger crea un directorio en ./debug-frames/ con timestamp. Ya está en .gitignore pero se acumula en disco. Limpiar periódicamente con rm -rf debug-frames/.

Colisión de nombres entre skills y agents

Un skill y un agente no deben tener el mismo name. Si hay colisión, Claude Code puede confundirlos. Verificar con:

grep -r '"name":' .claude-plugin/plugin.json | sort