documentation-fundamentals
Escribir Documentación Clara
La documentación deficiente desperdicia tiempo del equipo y genera confusión. Esta habilidad aplica estándares de documentación para archivos README, comentarios JSDoc y explicaciones en línea siguiendo el principio del POR QUÉ no del QUÉ. Obtén documentación consistente y mantenible que explica el contexto y la justificación.
Baixar o ZIP da skill
Upload no Claude
Vá em Configurações → Capacidades → Skills → Upload skill
Ative e comece a usar
Testar
A utilizar "documentation-fundamentals". Revisa el README y los comentarios en línea de mi proyecto
Resultado esperado:
- Evaluación del README: Falta sección de Por Qué que explique el problema que resuelve este proyecto
- Comentarios en línea que necesitan mejora: Líneas 24-26 solo repiten código, Líneas 89-91 están desactualizadas - dice filtrar inactivo pero el código filtra por rol
- JSDoc faltante: 3 funciones exportadas carecen de documentación
- Buenos ejemplos encontrados: Líneas 45-48 explican la justificación del margen de límite de tasa
A utilizar "documentation-fundamentals". Ayúdame a escribir JSDoc para mis funciones de API
Resultado esperado:
- Para función validateUser: Agregar @param email con tipo string, @returns ValidationResult, incluir ejemplo de uso, documentar throws AuthenticationError cuando las credenciales son inválidas
- Para función createSession: Agregar @param userId, @param expiresIn, @returns sessionToken, documentar que los tokens se renuevan silenciosamente
- Para función getUserProfile: Agregar @param userId, @returns UserProfile, incluir referencias @see a funciones relacionadas
A utilizar "documentation-fundamentals". ¿Qué hace que los comentarios en línea sean buenos?
Resultado esperado:
- Buenos comentarios explican el POR QUÉ: razón de negocio, caso límite, historia de decisiones
- Buenos comentarios referencian tickets o requisitos de interesados
- Evitar comentarios que solo describan lo que hace el código - el código muestra eso
- Eliminar números mágicos: usar constantes nombradas con comentarios explicativos
Auditoria de Segurança
SeguroThis is a pure prompt-based documentation skill containing only guidelines, examples, and templates for writing better documentation. The static findings are false positives caused by the scanner misinterpreting code examples and legitimate metadata fields. There is no executable code, no network access, no filesystem access, and no command execution in this skill. The skill only provides documentation review criteria and best practices.
Fatores de risco
🌐 Acesso à rede (1)
📁 Acesso ao sistema de arquivos (1)
⚙️ Comandos externos (39)
Pontuação de qualidade
O Que Você Pode Construir
Incorporación con READMEs Claros
Los nuevos miembros del equipo pueden ejecutar proyectos inmediatamente con documentación README completa que incluye pasos de instalación e inicio rápido.
Crear Proyectos Amigables para Contribuidores
Atrae contribuidores con instrucciones de instalación claras, guías de contribución y APIs bien documentadas.
Aplicar Estándares de Documentación del Equipo
Mantén documentación consistente en las bases de código con criterios de revisión accionables y alertas de anti-patrones.
Tente Estes Prompts
Revisa el archivo README de este proyecto. ¿Incluye estas secciones esenciales: Qué (descripción de una oración), Por Qué (problema resuelto), Instalación, Inicio Rápido y Contribución? Señala cualquier sección faltante y sugiere mejoras específicas.
Revisa los comentarios en línea en este código. Señala cualquier comentario que simplemente repita lo que hace el código (QUÉ) y reescríbelos para explicar el contexto y la justificación (POR QUÉ). Incluye la razón de negocio o referencia de ticket cuando corresponda.
Escribe documentación JSDoc completa para las funciones exportadas en este archivo. Incluye: descripción breve, descripciones de parámetros con tipos, descripción del valor de retorno, ejemplo de uso, y cualquier condición de error que pueda lanzarse. Referencia la implementación de la función para asegurar precisión.
Audita esta base de código para verificar la calidad de la documentación. Reporta: JSDoc faltante en funciones exportadas, comentarios desactualizados que contradicen el código, código comentado que debería eliminarse, números mágicos sin explicación, y READMEs vacíos o auto-generados que necesitan expansión.
Melhores Práticas
- Escribe comentarios que respondan al POR QUÉ no al QUÉ - el código ya muestra qué sucede
- Incluye contexto de negocio en los comentarios - números de tickets, requisitos de interesados, o explicaciones de casos límite
- Mantén los READMEs actualizados - un README obsoleto es peor que ninguno
- Usa JSDoc para todas las funciones exportadas - incluye ejemplos que muestren uso correcto
Evitar
- Comentar código obvio como Establecer x en 5 o Recorrer elementos
- Dejar código comentado en la base de código - usa git para recuperar código antiguo
- Escribir documentación una vez y nunca actualizarla cuando el código cambia
- Usar números mágicos sin explicar su significado u origen
Perguntas Frequentes
¿Qué herramientas funcionan con esta habilidad?
¿Esto genera documentación desde código?
¿Cómo es esto diferente de los generadores de documentación?
¿Mis datos están seguros al usar esta habilidad?
¿Por qué es importante el principio del POR QUÉ no del QUÉ?
¿Puede esto ayudar con la documentación de API?
Detalhes do Desenvolvedor
Autor
DanielPodolskyLicença
MIT
Repositório
https://github.com/DanielPodolsky/mentor-spec/tree/main/.claude/skills/fundamentals/documentationReferência
main
Estrutura de arquivos
📄 SKILL.md