Habilidades internas de Claude: Módulos personalizados que amplían Claude

Plataforma para programadores Claude (API)

También se puede acceder a las habilidades de Claude a través de la API de Claude. En esta sección, exploraremos cómo podemos imitar la interfaz de la aplicación Claude a través de la API de Claude.

Paso 1: Requisitos previos

Comienza instalando todas las dependencias de tiempo de ejecución:

• Anthropic para la API de Claude Messages

• pandas y openpyxl para leer hojas de horas desde Excel.

• reportlab para generar una factura PDF alternativa localmente 

!pip -q install anthropic pandas openpyxl reportlab

Ahora ya tenemos todas las dependencias instaladas.  A continuación, podemos configurar nuestra clave API.

Paso 2: Configura tu clave API

Antes de poder llamar a la API de mensajes, debemos autenticarnos. Este paso crea una única clave de acceso de aplicación ( anthropic.Client ) reutilizable con la clave API. 

import os, json, sys, re
import anthropic
from datetime import datetime, timedelta
API_KEY = "YOUR_ANTHROPIC_API_KEY"
client = anthropic.Client(api_key=API_KEY)

Inicia sesión en Anthropic Console y busca la pestaña «Claves API» en «Configuración». Haz clic en« » (Crear clave) y copia tu clave API de Anthropic.

Fuente: API antropológica

Nota: Si utilizas un cuaderno privado para uso personal, añade tu clave API. De lo contrario, utiliza una variable de entorno segura para que tu clave no quede expuesta en el cuaderno o en los registros.

El código anterior inicializa el cliente SDK de Anthropic y configura el entorno. A continuación, el objeto cliente se reutiliza para todas las llamadas posteriores a la API de mensajes.

Paso 3: Preprocesamiento de datos

En este paso, convertiremos nuestra hoja timesheet.xlsxen un objeto JSON limpio y predecible que la habilidad pueda consumir. Esto mantiene la lógica descendente simple y evita el frágil análisis sintáctico de los mensajes.

def load_invoice_from_timesheet(excel_path):
    import pandas as pd
    df = pd.read_excel(excel_path)
    df.columns = df.columns.str.strip()  
    invoice_period = "2025-10"
    if 'Date' in df.columns:
        first_date = str(df['Date'].iloc[0])
        date_match = re.search(r'(\d{2})\s+(\w+)\s+(\d{4})', first_date)
        if date_match:
            month_name = date_match.group(2)
            year = date_match.group(3)
            month_num = datetime.strptime(month_name[:3], '%b').month
            invoice_period = f"{year}-{month_num:02d}"   
    article_col = next((col for col in df.columns if 'article' in col.lower() and 'name' in col.lower()), None)
    amount_col = next((col for col in df.columns if 'amount' in col.lower()), None)
    topic_col = next((col for col in df.columns if 'topic' in col.lower()), None)
    line_items = []
    timesheet_articles = []
    
    for idx, row in df.iterrows():
        if pd.isna(row.get(article_col)) or row.get(article_col) == '':
            continue    
        article_name = str(row[article_col]).strip()
        amount = row.get(amount_col, 0) 
        if isinstance(amount, str):
            amount = float(amount.replace('$', '').replace(',', '').strip())
        line_items.append({
            "title": article_name,
            "rate_type": "flat",
            "qty": 1,
            "rate": float(amount)
        })  
        timesheet_articles.append({
            "title": article_name,
            "topic": str(row.get(topic_col, 'N/A')) if topic_col else 'N/A'
        })
    return {
        "client_name": "Client",
        "billing_contact": "billing@example.com",
        "invoice_period": invoice_period,
        "currency": "USD",
        "payment_terms": "Net-30",
        "line_items": line_items,
        "discount_pct": 0.0,
        "tax_pct": 0.0,
        "timesheet": timesheet_articles
    }

La función load_invoice_from_timesheet convierte un archivo Excel cargado en una carga JSON de factura normalizada.

• Lee el Excel con pandas y normaliza los encabezados de las columnas.

• A continuación, el código deduce invoice_period a partir de la primera fila Date (si existe) utilizando una expresión regular y un análisis sintáctico del mes.

• Finalmente detecta los nombres de las columnas para el título del artículo, la cantidad y el tema sin distinguir entre mayúsculas y minúsculas.

• Esto emite dos estructuras:

• line_items: Se utiliza para el cálculo de la facturación (tarifa plana por artículo en este caso).

• timesheet: Una lista plana de entradas de {title, topic} para un apéndice opcional.

• La expresión regular (\d{2})\s+(\w+)\s+(\d{4}) espera formatos como 01 Oct 2025. Ajústala si tu hoja utiliza otro formato.

• Las columnas o valores que faltan se gestionan omitiendo las filas vacías, o bien puedes ampliar el código para que falle rápidamente si es necesario.

Nuestra aportación ya está lista. A continuación, llamaremos a la habilidad Claude a través de la API para convertir la hoja de horas procesada en una factura editable.

Paso 4: Funciones auxiliares

En esta sección, definimos dos funciones auxiliares que simulan la ejecución de la herramienta que Claude solicita durante la ejecución de una habilidad. 

def execute_bash_tool(command):
    try:
        dangerous = ['rm -rf /', 'sudo', 'chmod', 'mkfs', '> /dev/']
        if any(d in command for d in dangerous):
            return f"Error: Command blocked for safety: {command}"
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=30,
            cwd=tempfile.gettempdir()
        )    
        output = result.stdout if result.stdout else result.stderr
        return output if output else "Command executed successfully"
    except subprocess.TimeoutExpired:
        return "Error: Command timed out"
    except Exception as e:
        return f"Error executing command: {str(e)}"
def execute_text_editor_tool(params):
    try:
        command = params.get('command')
        path = params.get('path')   
        if command == 'create':
            file_text = params.get('file_text', '')
            os.makedirs(os.path.dirname(path) if os.path.dirname(path) else '.', exist_ok=True)
            with open(path, 'w') as f:
                f.write(file_text)
            return f"File created: {path}"
        elif command == 'view':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                return content[:1000] 
            return f"Error: File not found: {path}"   
        elif command == 'str_replace':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                old_str = params.get('old_str', '')
                new_str = params.get('new_str', '')
                content = content.replace(old_str, new_str)
                with open(path, 'w') as f:
                    f.write(content)
                return f"File updated: {path}"
            return f"Error: File not found: {path}"    
        return f"Unknown command: {command}"
    except Exception as e:
        return f"Error: {str(e)}"

La función execute_bash_tool simula una herramienta bash segura para acciones basadas en habilidades. En primer lugar, bloquea patrones peligrosos como rm -rf /, sudo, chmod, mkfs, etc., a modo de barrera de seguridad, y ejecuta el comando con subprocess.run() en el directorio temporal del sistema operativo con un tiempo de espera obligatorio de 30 segundos.

La función execute_text_editor_tool proporciona una interfaz mínima de edición de texto utilizada por Skills. Admite tres comandos: « create » (para escribir un nuevo archivo con « file_text »), « view » (para devolver hasta 1000 caracteres de un archivo) y « str_replace » (para « new_str » en el lugar). También crea automáticamente carpetas principales para create, comprueba la existencia de archivos para view y str_replace, y escribe las actualizaciones en el disco.

Estos ayudantes te permiten completar un ciclo de uso de herramientas a nivel local con barreras de protección. Ahora, Skill puede solicitar modificaciones de archivos o acciones de terminal durante la generación de facturas sin poner en riesgo tu sistema.

Paso 5: Invoca la habilidad a través de la API. 

Este paso impulsa la generación de facturas de principio a fin a través de la API de Claude Messages. Envía una solicitud estructurada, habilita el uso de herramientas, itera a través de cualquier llamada a herramientas que solicite Claude y, finalmente, recopila cualquier archivo PDF generado de los directorios de trabajo y temporales.

def generate_invoice_with_claude(invoice): 
    user_text = f"""Generate a professional PDF invoice with the following data:
Client: {invoice['client_name']}
Period: {invoice['invoice_period']}
Currency: {invoice['currency']}
Payment Terms: {invoice['payment_terms']}
Line Items:
{json.dumps(invoice['line_items'], indent=2)}
Timesheet Articles:
{json.dumps(invoice['timesheet'], indent=2)}
Please create a professional PDF invoice with:
1. Invoice header with invoice number (INV-{invoice['invoice_period'].replace('-', '')}-001)
2. Client billing information
3. Line items table with amounts
4. Subtotal and total calculations
5. Timesheet section showing all articles and topics
Save the PDF as: invoice_{invoice['client_name'].lower()}_{invoice['invoice_period']}.pdf
""" 
    tools = [
        {"type": "bash_20250124", "name": "bash"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
    ]
    messages = [{"role": "user", "content": user_text}]
    iteration = 0
    max_iterations = 15   
    while iteration < max_iterations:
        iteration += 1
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=8192,
            tools=tools,
            messages=messages
        )   
        messages.append({"role": "assistant", "content": response.content}) 
        if response.stop_reason == "end_turn":
            break     
        if response.stop_reason == "tool_use":
            tool_results = []    
            for block in response.content:
                if block.type == "tool_use":
                    tool_name = block.name
                    tool_input = block.input
                    if tool_name == "bash":
                        result = execute_bash_tool(tool_input.get('command', ''))
                    elif tool_name == "str_replace_based_edit_tool":
                        result = execute_text_editor_tool(tool_input)
                    else:
                        result = f"Unknown tool: {tool_name}" 
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            messages.append({"role": "user", "content": tool_results})
        else:
            break
    pdf_files = []
    for file in os.listdir('.'):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            pdf_files.append(file)
    for file in os.listdir(tempfile.gettempdir()):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            temp_path = os.path.join(tempfile.gettempdir(), file)
            import shutil
            dest_path = os.path.join('.', file)
            shutil.copy2(temp_path, dest_path)
            pdf_files.append(file)   
    return pdf_files
def main():
    if len(sys.argv) < 2:
        print("Usage: python app.py <timesheet.xlsx>")
        sys.exit(1)    
    excel_file = sys.argv[1]  
    if not os.path.exists(excel_file):
        print(f"Error: File not found: {excel_file}")
        sys.exit(1)    
    try:
        invoice = load_invoice_from_timesheet(excel_file)
        pdf_files = generate_invoice_with_claude(invoice)    
        if pdf_files:
            for pdf in pdf_files:
                print(f"Invoice generated: {os.path.abspath(pdf)}")
        else:
            print("Error: No PDF file was generated.")     
    except Exception as e:
        print(f"Error: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)
if __name__ == "__main__":
    main()

La función « generate_invoice_with_claude » envía la factura normalizada a la API de Claude y controla la ejecución de la habilidad de principio a fin. Esto es lo que hace el código:

• Crea un informe claro ( user_text ) que incluye el cliente, el período, la moneda, los términos, las partidas y las entradas de la hoja de horas, además de requisitos de salida explícitos como el encabezado, las tablas, los totales y el nombre del archivo.

• A continuación, habilita la ejecución de la herramienta declarando un bash_number y un text_editor_number con un bucle de mensajes compatible con la herramienta que envía la solicitud, inspecciona stop_reason y, cuando se solicita tool_use, la envía a los ayudantes locales y devuelve tool_result bloques para continuar el intercambio.

• Finalmente, se detiene en end_turn o cuando se alcanza el límite del bucle, y luego escanea el directorio de trabajo y el directorio temporal del sistema operativo en busca de archivos que coincidan con invoice*.pdf. Copia cualquier artefacto temporal de vuelta a la carpeta del proyecto y devuelve la lista de archivos PDF encontrados.

• La función main proporciona un comando CLI sencillo: python app.py , que valida la ruta de entrada y, a continuación, ejecuta el canal: load_invoice_from_timesheet(...) para crear la carga útil, y generate_invoice_with_claude(...) para invocar la habilidad y recopilar los archivos PDF.

Con esto, la llamada a la API debería generar un PDF listo para el cliente. Si no aparece ningún archivo, revisa los registros de tool_result y la configuración de Skill, y vuelve a intentarlo con una pequeña hoja de prueba.

Conclusión

Ahora tienes un generador automático de facturas que funciona con Claude Skills, y la API es capaz de convertir hojas de cálculo sin procesar en facturas listas para enviar a los clientes. Esta demostración muestra lo mejor de Skills: configuración portátil, activación automática, ejecución de código determinista y resultados consistentes en toda la aplicación y la API sin necesidad de recrear indicaciones en cada hilo. Claude Skills ofrece resultados consistentes en distintos contextos, lo que supone un conocimiento del dominio reutilizable y respaldado por código. Aunque las habilidades pueden ejecutar código, debes garantizar la seguridad habilitando solo las habilidades de confianza, utilizando controles a nivel de organización y revisando las actualizaciones antes de su implementación.

Para ir más allá, explora la documentación sobre habilidades de Anthropic y la consola para el control de versiones y las actualizaciones, y luego empieza a componer múltiples habilidades para crear flujos de trabajo integrales.