Habilidades internas de Claude: Módulos personalizados que ampliam o Claude

Plataforma de desenvolvimento Claude (API)

As habilidades do Claude também podem ser acessadas pela API do Claude. Nesta seção, vamos ver como podemos imitar a interface do aplicativo Claude usando a API do Claude.

Passo 1: Pré-requisitos

Comece instalando todas as dependências de tempo de execução:

• Anthropic para a API Claude Messages

• pandas e openpyxl para ler planilhas de horas trabalhadas do Excel

• reportlab para gerar uma fatura PDF alternativa localmente 

!pip -q install anthropic pandas openpyxl reportlab

Agora temos todas as dependências instaladas.  Depois, dá pra configurar a nossa chave API.

Passo 2: Configure sua chave API

Antes de chamarmos a API Mensagens, precisamos fazer a autenticação. Essa etapa cria um único token de acesso de sessão ( anthropic.Client ) reutilizável com a chave da 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)

Faça login no Anthropic Console e procure a aba Chaves de API em Configurações. Clique em“ ” (Criar chave) e copie sua chave da API da Anthropic.

Fonte: API Antrópica

Observação: Se você estiver usando um caderno privado para uso pessoal, adicione sua chave API. Caso contrário, use uma variável de ambiente segura para que sua chave não fique exposta no notebook ou nos registros.

O código acima inicializa o cliente Anthropic SDK e configura o ambiente. O objeto cliente é então reutilizado para todas as chamadas subsequentes da API de mensagens.

Passo 3: Pré-processamento de dados

Nesta etapa, vamos transformar nossa planilha timesheet.xlsxem um objeto JSON limpo e previsível que a Skill pode usar. Isso mantém a lógica a jusante simples e evita a análise frágil de prompts.

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
    }

A função load_invoice_from_timesheet transforma um arquivo Excel que você carregou em uma carga JSON normalizada de fatura.

• Ele lê o Excel com pandas e normaliza os cabeçalhos das colunas.

• O código então descobre o invoice_period a partir da primeira linha Date (se tiver) usando uma expressão regular e analisando o mês.

• Finalmente, ele detecta os nomes das colunas para título do artigo, valor e tópico sem se importar com maiúsculas e minúsculas.

• Isso gera duas estruturas:

• line_items: Isso é usado para cálculos de faturamento (taxa fixa por artigo, neste caso).

• timesheet: Uma lista simples de entradas {title, topic} para um apêndice opcional.

• A expressão regular (\d{2})\s+(\w+)\s+(\d{4}) espera formatos como 01 Oct 2025. Se a sua planilha usa outro formato, dá um jeito nela.

• As colunas/valores que faltam são tratados ignorando as linhas vazias, ou você pode estender o código para falhar rapidamente, se necessário.

Nossa contribuição já está pronta. Depois, vamos chamar a habilidade Claude pela API pra transformar a planilha de horas processada numa fatura que dá pra editar.

Passo 4: Funções auxiliares

Nesta seção, vamos definir duas funções auxiliares que simulam a execução da ferramenta que o Claude pede durante uma execução da Skill. 

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)}"

A função execute_bash_tool simula uma ferramenta bash segura para ações orientadas por habilidades. Primeiro, ele bloqueia padrões perigosos como rm -rf /, sudo, chmod, mkfs, etc., como uma porta de segurança, e executa o comando com subprocess.run() no diretório temporário do sistema operacional com um tempo limite forçado de 30 segundos.

A função ` execute_text_editor_tool ` oferece uma interface básica de edição de texto usada pelo Skills. Ele suporta três comandos, a saber: ` create ` (para gravar um novo arquivo com ` file_text`), ` view ` (para retornar até 1.000 caracteres de um arquivo) e ` str_replace ` (para ` new_str ` no local). Ele também cria automaticamente pastas pai para create, verifica a existência de arquivos para view e str_replace e grava as atualizações de volta no disco.

Esses auxiliares permitem que você complete um ciclo de uso de ferramentas localmente com proteções. Agora, o Skill pode pedir edições de arquivos ou ações de shell durante a geração de faturas sem colocar seu sistema em risco.

Passo 5: Chame a habilidade pela API 

Essa etapa faz a geração completa da fatura usando a API Claude Messages. Ele manda uma solicitação estruturada, permite o uso de ferramentas, repete todas as chamadas de ferramentas que o Claude pede e, por fim, junta todos os arquivos PDF gerados dos diretórios de trabalho e temporários.

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()

A função generate_invoice_with_claude manda a fatura normalizada para a API Claude e controla a execução da Skill do começo ao fim. E aí, o que o código faz:

• Ele cria um arquivo user_text bem claro que inclui cliente, período, moeda, termos, itens de linha e entradas da planilha de horas, além de requisitos de saída explícitos, como cabeçalho, tabelas, totais e nome do arquivo.

• Em seguida, ele permite a execução da ferramenta declarando um bash_number e um text_editor_number com um loop de mensagens compatível com a ferramenta que envia a solicitação, inspeciona stop_reason e, quando tool_use é solicitado, ele despacha para auxiliares locais e retorna tool_result blocos para continuar a troca.

• Por fim, ele para em end_turn ou quando o limite do loop é atingido, então verifica o diretório de trabalho e o diretório temporário do sistema operacional em busca de arquivos que correspondam a invoice*.pdf. Ele copia todos os artefatos temporários de volta para a pasta do projeto e retorna a lista de PDFs encontrados.

• A função main oferece um comando CLI simples: python app.py , que verifica o caminho de entrada e, em seguida, executa o pipeline: load_invoice_from_timesheet(...) para criar a carga útil e generate_invoice_with_claude(...)para chamar a Skill e coletar PDFs.

Com isso pronto, a chamada da API deve gerar um PDF pronto para o cliente. Se nenhum arquivo aparecer, dá uma olhada nos registros tool_result e na configuração da Skill, depois tenta de novo com uma pequena folha de teste.

Conclusão

Agora você tem um Gerador de Faturas Automáticas funcionando com a ajuda do Claude Skills, e a API consegue transformar planilhas em faturas prontas para os clientes. Essa demonstração mostra o que o Skills faz de melhor, ou seja, configuração portátil, ativação automática, execução de código determinístico e resultados consistentes em todo o aplicativo e API sem precisar recriar prompts em cada thread. O Claude Skills dá resultados consistentes em vários contextos, que são conhecimentos reutilizáveis do domínio e baseados em código. Embora as Skills possam executar código, você ainda precisa garantir a segurança ativando apenas Skills confiáveis, usando controles no nível da organização e revisando as atualizações antes da implementação.

Para ir mais longe, dá uma olhada nos documentos sobre Skills da Anthropic e no Console para ver versões e atualizações, e depois começa a criar várias Skills para montar fluxos de trabalho completos.