Anthropic Agent Skills in TypeScript: Package Reusable Instructions and Code as Tools

// invoice-processing/ — the skill folder
invoice-processing/
├── SKILL.md            # required: frontmatter + instructions
├── REFERENCE.md        # optional: detailed rules, loaded only when needed
└── scripts/
    └── validate_invoice.py   # optional: deterministic code Claude runs via bash

<!-- invoice-processing/SKILL.md -->
---
name: invoice-processing
description: Extract structured data from invoices (PDF or text) and validate it. Use when the user uploads an invoice, asks to parse a bill, or mentions invoice extraction, line items, or invoice totals.
---

# Invoice Processing

Extract invoice data into this exact JSON shape, then validate it before returning.

## Extraction

Pull these fields:
- `invoice_number` (string)
- `issue_date` (ISO 8601 date)
- `currency` (ISO 4217 code, e.g. "USD")
- `line_items`: array of `{ description, quantity, unit_price, amount }`
- `subtotal`, `tax`, `total` (numbers)

For PDFs, read text with `pdfplumber` (pre-installed). Never guess a field — if it
is missing or ambiguous, set it to null and add a note.

## Validation

After extracting, run the validation script and include its result:

```bash
python scripts/validate_invoice.py extracted.json

The `description` is doing real work — it's the only part Claude sees at startup, so it has to say *what the skill does and when to reach for it*. Write it for the model, not for a human reader.

**Gotcha #1:** the `name` field has rules that will bite you. Lowercase letters, numbers, and hyphens only; max 64 characters; and it **cannot contain the words "anthropic" or "claude"**. Naming your skill `claude-invoice-helper` returns a 400. The `description` maxes out at 1024 characters.

## The validation script

Scripts are where you put logic that must be *deterministic* — Claude is great at reading a messy PDF, terrible at reliably adding up 40 line items. Offload the math:

```python
# invoice-processing/scripts/validate_invoice.py
import json
import sys
from decimal import Decimal


def validate(invoice: dict) -> dict:
    errors: list[str] = []

    required = ["invoice_number", "issue_date", "currency", "total"]
    for field in required:
        if invoice.get(field) in (None, ""):
            errors.append(f"missing required field: {field}")

    items = invoice.get("line_items") or []
    if not items:
        errors.append("no line items found")

    # Line items must sum to subtotal (money math uses Decimal, never float)
    line_sum = sum(Decimal(str(i.get("amount", 0))) for i in items)
    subtotal = Decimal(str(invoice.get("subtotal", 0)))
    if items and abs(line_sum - subtotal) > Decimal("0.01"):
        errors.append(f"line items sum to {line_sum}, but subtotal is {subtotal}")

    # subtotal + tax must equal total
    tax = Decimal(str(invoice.get("tax", 0)))
    total = Decimal(str(invoice.get("total", 0)))
    if abs(subtotal + tax - total) > Decimal("0.01"):
        errors.append(f"subtotal ({subtotal}) + tax ({tax}) != total ({total})")

    return {"valid": len(errors) == 0, "errors": errors}


if __name__ == "__main__":
    with open(sys.argv[1]) as f:
        result = validate(json.load(f))
    print(json.dumps(result))
    sys.exit(0 if result["valid"] else 1)

pnpm add @anthropic-ai/sdk

// src/skills/upload-invoice-skill.ts
import Anthropic, { toFile } from '@anthropic-ai/sdk'
import fs from 'fs'

const client = new Anthropic() // reads ANTHROPIC_API_KEY from the environment

export async function uploadInvoiceSkill(): Promise<{ id: string; version: string }> {
    try {
        const skill = await client.beta.skills.create({
            display_title: 'Invoice Processing',
            files: [
                await toFile(
                    fs.createReadStream('invoice-processing/SKILL.md'),
                    'invoice-processing/SKILL.md',
                    { type: 'text/markdown' }
                ),
                await toFile(
                    fs.createReadStream('invoice-processing/REFERENCE.md'),
                    'invoice-processing/REFERENCE.md',
                    { type: 'text/markdown' }
                ),
                await toFile(
                    fs.createReadStream('invoice-processing/scripts/validate_invoice.py'),
                    'invoice-processing/scripts/validate_invoice.py',
                    { type: 'text/x-python' }
                ),
            ],
        })

        console.log(`Created skill ${skill.id} (version ${skill.latest_version})`)
        return { id: skill.id, version: skill.latest_version }
    } catch (err) {
        if (err instanceof Anthropic.APIError) {
            // 400s here are almost always a bad `name` or `description` in SKILL.md
            console.error(`Skill upload failed (${err.status}): ${err.message}`)
        }
        throw err
    }
}

// src/skills/process-invoice.ts
import Anthropic from '@anthropic-ai/sdk'
import fs from 'fs'

const client = new Anthropic()

export async function processInvoice(skillId: string, pdfPath: string) {
    // 1. Upload the invoice file so the container can read it
    const file = await client.beta.files.upload(
        { file: fs.createReadStream(pdfPath) },
        { headers: { 'anthropic-beta': 'files-api-2025-04-14' } }
    )

    // 2. Run the message with the skill loaded
    const response = await client.beta.messages.create({
        model: 'claude-opus-4-8',
        max_tokens: 4096,
        betas: [
            'code-execution-2025-08-25',
            'skills-2025-10-02',
            'files-api-2025-04-14',
        ],
        container: {
            skills: [{ type: 'custom', skill_id: skillId, version: 'latest' }],
        },
        tools: [{ type: 'code_execution_20250825', name: 'code_execution' }],
        messages: [
            {
                role: 'user',
                content: [
                    { type: 'text', text: 'Extract and validate this invoice. Return the JSON.' },
                    { type: 'container_upload', file_id: file.id },
                ],
            },
        ],
    })

    for (const block of response.content) {
        if (block.type === 'text') return block.text
    }
    return null
}

// src/skills/version-invoice-skill.ts
import Anthropic, { toFile } from '@anthropic-ai/sdk'
import fs from 'fs'

const client = new Anthropic()

export async function publishNewVersion(skillId: string) {
    // You can upload a whole folder as a single zip for a new version
    const version = await client.beta.skills.versions.create(skillId, {
        files: [await toFile(fs.createReadStream('invoice-processing.zip'), 'skill.zip')],
    })
    console.log(`Published version ${version.version}`)
    return version.version
}

// src/skills/invoice-skill.test.ts
import { describe, it, expect } from 'vitest'
import { processInvoice } from './process-invoice'

describe('invoice-processing skill', () => {
    it('flags an invoice whose totals do not add up', async () => {
        // fixtures/bad-total.pdf: subtotal 100 + tax 10, total wrongly printed as 120
        const result = await processInvoice(process.env.SKILL_ID!, 'fixtures/bad-total.pdf')
        expect(result).toMatch(/subtotal.*tax.*!= total/i)
    })

    it('extracts a clean invoice without errors', async () => {
        const result = await processInvoice(process.env.SKILL_ID!, 'fixtures/clean.pdf')
        expect(result).toMatch(/"valid":\s*true/)
    })
})