Yinyo Skill Craft — Skill 工匠
Herramienta de auditoría de ingeniería de Skills y reparación interactiva. Basada en la guía oficial de Perplexity Agents Team + normas de codificación Karpathy CLAUDE.md + experiencia práctica de la serie yinyo.
Nueva capacidad: soporte para reparación automática + modo de confirmación del usuario.
Reglas principales
1. El Skill es un directorio, no un archivo
- Archivo único > 50KB → debe dividirse en estructura hub-and-spoke
- Estructura estándar: SKILL.md + README.md + docs/ + examples/ + subskills/
- Anidamiento multinivel: 300 temas → 20 dominios → 15 temas/dominio
2. La descripción es un desencadenante de ruta
- Debe comenzar con
Load when... - Explica la condición de activación, no una lista de funciones
- Mantenerse en 50 palabras o menos
3. Carga progresiva de tres niveles
| Nivel | Presupuesto de tokens | Contenido | Frecuencia de pago |
|---|---|---|---|
| Índice | ~100 | nombre + descripción | Por sesión |
| Cuerpo | ~5000 | Reglas principales + referencia rápida | Tras la carga hasta compactación |
| Tiempo de ejecución | Sin límite | docs/ + examples/ + subskills/ | Cuando se usen |
4. Eliminar contenido conocido por el modelo
- Explicar conceptos básicos → eliminar
- Principios de programación generales → eliminar
- "Si es fácil de explicar, el modelo ya lo sabe. Bórralo."
5. Cuatro principios de codificación de Karpathy
- Piensa antes de codificar: si no estás seguro, pregunta
- Simplicidad primero: si puedes escribirlo en 200 líneas, no escribas 500
- Cambios quirúrgicos: toca solo lo que es necesario tocar
- Ejecución impulsada por objetivos: define objetivos verificables
Flujo de reparación interactiva (nuevo)
Principios de reparación
- Riesgo bajo (estructura, formato, versión) → ejecutar automáticamente, informar después
- Riesgo medio (reescritura de descripción) → mostrar comparación antes/después, confirmación del usuario
- Riesgo alto (eliminación de contenido) → enumerar elementos a eliminar, confirmar uno por uno
Alcance de reparación
| Tipo de reparación | Ejemplo | Nivel de riesgo |
|---|---|---|
| Ajuste estructural | Dividir archivo único en directorio | Bajo |
| Reescritura de descripción | Cambiar a Load when... | Medio |
| Eliminación de contenido | Eliminar contenido conocido por el modelo | Alto |
| Sincronización de versión | Actualizar version/last_updated | Bajo |
| Normalización de formato | Completar frontmatter | Bajo |
Flujo de reparación
Auditar → Listar problemas → Clasificar riesgos → Confirmación del usuario → Reparación automática → Segunda auditoría → Informar resultados
Validación posterior a la reparación
- Ejecutar automáticamente una segunda auditoría
- Comparar puntuaciones antes y después de la reparación
- Generar informe de reparación (qué se cambió, por qué se cambió, cambio de puntuación)
Flujo de auditoría
Entrada
El usuario proporciona:
- Ruta del directorio del Skill, o
- Contenido de SKILL.md
Salida
Generar informe de auditoría:
## Informe de auditoría: {skill-name}
### Auditoría estructural
- [PASS/WARN/FAIL] Estructura del directorio
- [PASS/WARN/FAIL] Tamaño del archivo
- [PASS/WARN/FAIL] Profundidad de jerarquía
### Auditoría de contenido
- [PASS/WARN/FAIL] Redacción de la descripción
- [PASS/WARN/FAIL] Detección de contenido conocido por el modelo
- [PASS/WARN/FAIL] Densidad de señales
### Gestión de versiones
- [PASS/WARN/FAIL] Formato del número de versión
- [PASS/WARN/FAIL] Estado de sincronización
### Puntuación total: {X}/100
### Recomendaciones: {acciones prioritarias}
Lista de detección de antipatrones
Antipatrones estructurales
- Archivo único hinchado (> 50KB)
- Descripción demasiado larga (> 100 tokens)
- Sin jerarquía (> 50 temas en plano)
- Sin gestión de versiones
Antipatrones de contenido
- Contenido conocido por el modelo (explicación de conceptos básicos)
- Sobreingeniería (capas de abstracción > necesidad real)
- Simulación de procesos (cumplimiento de restricciones en lugar de calidad del producto final)
- Sin criterios de validación
Puntos débiles específicos de yinyo
- Dudas al revertir versiones (no revertir inmediatamente cuando la calidad baja)
- Cuanto más completo el proceso, peor la calidad (lección de yinyo-writer)
- Archivo único de 277KB (lección de yinyo-liuyao)
Plantilla de sugerencias de reparación
Archivo único hinchado → Dividir
Original: SKILL.md (277KB)
Nuevo:
├── SKILL.md (5KB: reglas principales)
├── docs/
│ ├── rules.md (50KB: 120 reglas)
│ ├── examples.md (100KB: 412 ejemplos de hexagramas)
│ └── reference.md (30KB: tabla de 64 hexagramas)
└── subskills/
├── edge-case-1.md
└── edge-case-2.md
Descripción incorrecta → Corregir
❌ "Este Skill te ayuda a escribir artículos."
✅ "Load when the user needs to write a WeChat public account article."
Referencia rápida
Nomenclatura de Skills
yinyo-{domain}-{action}
Tamaño de archivos
- Índice: < 1KB
- Cuerpo: < 50KB
- Tiempo de ejecución: sin límite
Gestión de versiones
- SemVer: MAJOR.MINOR.PATCH
- Cada actualización sincronizar: SKILL.md + README.md + Git commit + memory
Palabras desencadenantes de reparación
- "Repara este Skill" → entrar en modo de reparación interactiva
- "Reparación automática" → ejecutar reparaciones de bajo riesgo
- "Ayúdame a cambiarlo" → mostrar sugerencias de cambio, esperar confirmación