Skills de SDD y tools de LangChain: ¿son lo mismo? La distinción que confunde a los equipos

Cuando un equipo empieza a trabajar con SDD y LangChain al mismo tiempo, una confusión aparece con regularidad: mezclar las skills del asistente de desarrollo con las tools del agente en producción. Ambas "son cosas que el agente usa", ambas "son archivos de instrucciones"… pero ahí acaban las similitudes.

La confusión lleva a intentar hacer que el agente de producción "sea consciente" de las skills de SDD, a incluir skills como herramientas en el chain de LangChain, o a tratar de que el agente de producción siga los mismos patrones que el asistente de codificación. Esto es innecesario, sobre-ingenierizado y mezcla dos mundos que operan en momentos completamente distintos.

Las skills de SDD (en .claude/skills/o en agents.md) son archivos de texto que el asistente de codificación — Claude Code, Cursor, Copilot — carga en su contexto mientras el desarrollador está escribiendo código. Definen qué patrones usar, qué librerías preferir, cómo estructurar los tests, qué convenciones de naming seguir.

Cuando el desarrollador le pide al asistente "crea una nueva tool para buscar en Jira", el asistente consulta las skills para decidir: ¿qué librería de cliente HTTP usar? ¿Cómo estructurar el manejo de errores? ¿Qué patrón de docstring seguir? Las skills responden esas preguntas de forma consistente a lo largo de todo el proyecto.

# Skill: LangChain Tools

## Patrón estándar para tools
- Decorar siempre con @tool
- Docstring en español, primera persona del agente
- Incluir condición de activación explícita
- Type hints completos en todos los parámetros
- Manejo de errores con try/except + logger

## Ejemplo canónico
@tool
def nombre_de_la_tool(param: str) -> str:
    """
    [Qué hace]. [Cuándo invocarla]. [Qué devuelve].
    Args:
        param: descripción del parámetro.
    """
    try:
        result = external_call(param)
        return format_result(result)
    except Exception as e:
        logger.error(f"Tool error: {e}")
        return f"Error: {str(e)}"

Las tools de LangChain son componentes del agente de producción. Cuando el agente recibe un mensaje de un usuario en producción y decide que necesita buscar en Jira, LangChain ejecuta la función Python decorada con@toolque hace exactamente esa búsqueda. El resultado vuelve al contexto del LLM y el agente continúa generando su respuesta.

Las tools de producción no saben nada de las skills de SDD que se usaron para crearlas. No las consumen, no las referencian, no las necesitan. Las skills sirvieron su propósito durante el desarrollo — guiar al asistente de codificación para que generara el código correcto. Una vez el código está escrito, las skills son irrelevantes para el runtime.