Bên trong Claude Skills: Mô-đun tùy chỉnh mở rộng Claude

Nền tảng nhà phát triển Claude (API)

Bạn cũng có thể truy cập Claude skills qua Claude API. Ở phần này, chúng ta sẽ khám phá cách mô phỏng giao diện ứng dụng Claude thông qua Claude API.

Bước 1: Điều kiện tiên quyết

Bắt đầu bằng cách cài đặt tất cả các phụ thuộc thời gian chạy:

• Anthropic cho Claude Messages API

• pandas và openpyxl để đọc bảng chấm công từ Excel

• reportlab để tạo hóa đơn PDF dự phòng tại máy 

!pip -q install anthropic pandas openpyxl reportlab

Giờ chúng ta đã cài đặt xong các phụ thuộc. Tiếp theo, cấu hình khóa API của bạn.

Bước 2: Cấu hình khóa API

Trước khi gọi Messages API, chúng ta cần xác thực. Bước này tạo một anthropic.Client dùng lại được với khóa 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)

Đăng nhập vào Anthropic Console và tìm tab API keys trong phần Settings. Nhấp Create Key và sao chép khóa API Anthropic của bạn.

Nguồn: Anthropic API

Lưu ý: Nếu bạn dùng notebook riêng cho mục đích cá nhân, hãy thêm khóa API của bạn. Nếu không, hãy dùng biến môi trường an toàn để khóa không lộ trong notebook hoặc log.

Đoạn mã trên khởi tạo client SDK Anthropic và thiết lập môi trường. Đối tượng client sẽ được tái sử dụng cho mọi lần gọi Messages API tiếp theo.

Bước 3: Tiền xử lý dữ liệu

Ở bước này, chúng ta sẽ chuyển trang timesheet.xlsx thành một đối tượng JSON gọn gàng, có thể dự đoán mà Skill có thể tiêu thụ. Cách này giữ cho logic phía sau đơn giản và tránh việc phân tích prompt mong manh.

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
    }

Hàm load_invoice_from_timesheet chuyển đổi tệp Excel được tải lên thành một payload JSON hóa đơn đã chuẩn hóa.

• Đọc Excel bằng pandas và chuẩn hóa tiêu đề cột.

• Sau đó suy luận invoice_period từ hàng Date đầu tiên (nếu có) bằng regex và phân tích tháng.

• Cuối cùng phát hiện tên cột cho tiêu đề bài viết, số tiền và chủ đề theo cách không phân biệt hoa thường.

• Hàm xuất ra hai cấu trúc:

• line_items: Dùng cho tính toán thanh toán (ở đây là giá cố định mỗi bài).

• timesheet: Danh sách phẳng các mục {title, topic} cho phần phụ lục tùy chọn.

• Regex (\d{2})\s+(\w+)\s+(\d{4}) kỳ vọng các định dạng như 01 Oct 2025; hãy điều chỉnh nếu trang của bạn dùng định dạng khác.

• Các cột/giá trị thiếu được xử lý bằng cách bỏ qua hàng trống, hoặc bạn có thể mở rộng mã để báo lỗi sớm nếu cần.

Đầu vào của chúng ta đã sẵn sàng. Tiếp theo, chúng ta sẽ gọi Claude Skill qua API để biến bảng chấm công đã xử lý thành hóa đơn có thể chỉnh sửa.

Bước 4: Hàm trợ giúp

Ở phần này, chúng ta định nghĩa hai hàm trợ giúp mô phỏng việc thực thi công cụ mà Claude yêu cầu trong quá trình chạy 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)}"

Hàm execute_bash_tool mô phỏng một công cụ bash an toàn cho các hành động do Skill điều khiển. Nó chặn trước các mẫu nguy hiểm như rm -rf /, sudo, chmod, mkfs, v.v. như một cổng an toàn và chạy lệnh bằng subprocess.run() trong thư mục tạm của hệ điều hành với thời gian chờ 30 giây.

Hàm execute_text_editor_tool cung cấp giao diện chỉnh sửa văn bản tối thiểu dùng bởi Skills. Nó hỗ trợ ba lệnh là create (để ghi tệp mới với file_text), view (trả về tối đa 1.000 ký tự của tệp) và str_replace (thay thế tại chỗ bằng new_str). Nó cũng tự động tạo thư mục cha cho create, kiểm tra sự tồn tại tệp cho view và str_replace, và ghi cập nhật trở lại đĩa.

Các hàm trợ giúp này cho phép bạn hoàn tất vòng lặp sử dụng công cụ tại chỗ với hàng rào an toàn. Từ đó, Skill có thể yêu cầu sửa tệp hoặc thao tác shell trong lúc tạo hóa đơn mà không gây rủi ro cho hệ thống của bạn.

Bước 5: Gọi Skill qua API 

Bước này điều khiển quá trình tạo hóa đơn đầu-cuối thông qua Claude Messages API. Nó gửi yêu cầu có cấu trúc, bật sử dụng công cụ, lặp qua mọi lệnh gọi công cụ mà Claude yêu cầu và cuối cùng thu thập các tệp PDF được tạo từ thư mục làm việc và thư mục tạm.

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

Hàm generate_invoice_with_claude gửi hóa đơn đã chuẩn hóa tới Claude API và điều khiển thực thi Skill đầu-cuối. Cụ thể mã làm những việc sau:

• Xây dựng user_text rõ ràng, nhúng thông tin khách hàng, kỳ, tiền tệ, điều khoản, các dòng mục và danh sách bảng chấm công, kèm yêu cầu đầu ra tường minh như tiêu đề, bảng, tổng cộng và tên tệp.

• Sau đó bật thực thi công cụ bằng cách khai báo bash_number và text_editor_number với vòng lặp thông điệp nhận biết công cụ: gửi yêu cầu, kiểm tra stop_reason, và khi yêu cầu tool_use, sẽ chuyển tới các hàm trợ giúp cục bộ và trả về các khối tool_result để tiếp tục trao đổi.

• Cuối cùng dừng ở end_turn hoặc khi đạt giới hạn vòng lặp, sau đó quét thư mục làm việc và thư mục tạm của hệ điều hành để tìm các tệp khớp invoice*.pdf. Bất kỳ tạo phẩm tạm nào sẽ được sao chép về thư mục dự án và trả về danh sách PDF tìm thấy.

• Hàm main cung cấp lệnh CLI đơn giản: python app.py <timesheet.xlsx>, xác thực đường dẫn đầu vào, rồi chạy pipeline: load_invoice_from_timesheet(...) để dựng payload, và generate_invoice_with_claude(...)  để gọi Skill và thu thập PDF.

Với thiết lập này, cuộc gọi API sẽ tạo ra một PDF sẵn sàng cho khách hàng. Nếu không thấy tệp, hãy kiểm tra log tool_result và cấu hình Skill, sau đó thử lại với một bảng nhỏ.

Kết luận

Giờ bạn đã có một Trình tạo hóa đơn tự động hoạt động nhờ Claude Skills, và API có khả năng biến bảng tính thô thành hóa đơn sẵn sàng cho khách hàng. Bản demo này cho thấy thế mạnh của Skills: thiết lập di động, tự động kích hoạt, thực thi mã mang tính xác định và kết quả nhất quán trên ứng dụng và API mà không phải tạo lại prompt trong mọi chủ đề. Claude Skills trả về đầu ra nhất quán trên các ngữ cảnh, tức là tri thức miền có thể tái sử dụng và được hậu thuẫn bằng mã. Dù Skills có thể thực thi mã, bạn vẫn phải thực thi bảo mật bằng cách chỉ bật các Skill tin cậy, dùng kiểm soát ở cấp tổ chức và rà soát cập nhật trước khi triển khai.

Để tìm hiểu thêm, hãy khám phá tài liệu Skills của Anthropic và Console để quản lý phiên bản và nâng cấp, rồi bắt đầu kết hợp nhiều Skill để xây dựng các quy trình đầu-cuối.