Custom skills in container parameter break prompt caching - consistent skills list produces non-deterministic cache prefix

[rohanlad]

Bug Description

When passing custom skills in the container parameter, prompt caching fails on the message prefix. The skills list is identical on every request (same skill_ids, same types), yet cache_read_input_tokens shows the message-level cache is never read. The same request WITHOUT skills in the container (container={"skills": []}) caches correctly.

Evidence

Scenario	Turn	Request ID	cache_read	cache_write	Result
container={"skills": []}	1	req_011CZrmGrt9icQRYZk43zYuG	0	35301	Expected (cold)
container={"skills": []}	2	req_011CZrmH1kTHygE588SePDwg	35301	155	HIT - reads full prefix
container={"skills": [8 custom skills]}	1	req_011CZrhUg87qqzAC5uGD67GJ	0	37097	Expected (cold)
container={"skills": [8 custom skills]}	2	req_011CZrhV5bVzxmFwvRYRAfvD	0	37327	MISS - should have read ~37097

With skills present, Turn 2 reads cache_read_input_tokens=0 when it should read the full prefix from Turn 1. Without skills, caching works correctly.

Additional details

• Removing "version": "latest" from skills config does not help
• The skills list is a compile-time constant (nothing changes between requests)
• 5-minute TTL, ~37k tokens in both scenarios
• With skills, Turn 2 does show read=33852 at the system+tools level but write=3448 on messages, suggesting the resolved skills content differs between requests

Hypothesis

The API resolves custom skills server-side on each request, and this resolution produces non-deterministic output (different serialization, internal metadata, ordering, etc.) that changes the cache prefix hash even though the client-side input is identical.

Impact

Any API user with custom skills cannot benefit from message-level prompt caching. This significantly increases costs and latency for multi-turn conversations using skills.

Environment

• Package: anthropic (Python SDK)
• Model: claude-sonnet-4-6
• Betas: compact-2026-01-12, files-api-2025-04-14, skills-2025-10-02
• Method: client.beta.messages.stream()

[karpetrosyan]

Hey! Could you share the MRE so we can run it and see it in a real example?

[rohanlad]

@karpetrosyan Here's the MRE. We've also discovered a more specific trigger: the issue only occurs when custom skills are combined with compact-2026-01-12 and/or files-api-2025-04-14 betas. With just skills-2025-10-02 alone, caching works correctly.

Results:

Betas	Container	Turn 2 cache_read	Result
skills-2025-10-02 only	{"skills": []}	matches Turn 1 write	HIT
skills-2025-10-02 only	{"skills": [custom skills]}	matches Turn 1 write	HIT
All 3 betas	{"skills": []}	matches Turn 1 write	HIT
All 3 betas	{"skills": [custom skills]}	0	MISS

MRE:

"""
Minimal Reproducible Example: Custom skills in container break prompt caching
when combined with compact-2026-01-12 and files-api-2025-04-14 betas.

Requirements: pip install anthropic
Set ANTHROPIC_API_KEY env var.
Replace SKILLS list with your own custom skill IDs.
"""
import anthropic
import uuid

client = anthropic.Anthropic()  # Uses ANTHROPIC_API_KEY env var

MSG = "Explain quantum mechanics in detail. " * 100
BETAS = ["compact-2026-01-12", "files-api-2025-04-14", "skills-2025-10-02"]

# Replace with your own custom skill IDs
SKILLS = [
    {"type": "custom", "skill_id": "YOUR_CUSTOM_SKILL_ID_1"},
    {"type": "custom", "skill_id": "YOUR_CUSTOM_SKILL_ID_2"},
]

CODE_EXEC = {"type": "code_execution_20260120", "name": "code_execution"}


def test(label, container):
    # Unique system prompt per test to avoid cross-test cache hits
    uid = uuid.uuid4().hex[:8]
    sys = [{"type": "text", "text": f"Session {uid}. You are helpful. " * 600}]

    m1 = [{"role": "user", "content": [{"type": "text", "text": MSG}]}]
    with client.beta.messages.stream(
        betas=BETAS,
        model="claude-sonnet-4-6",
        max_tokens=8000,
        cache_control={"type": "ephemeral"},
        system=sys,
        tools=[CODE_EXEC],
        messages=m1,
        thinking={"type": "enabled", "budget_tokens": 2048},
        container=container,
    ) as s:
        r1 = s.get_final_message()
    u1 = r1.usage

    # Build assistant content for Turn 2
    ac = []
    for b in r1.content:
        d = b.model_dump()
        if d.get("type") == "thinking":
            ac.append({"type": "thinking", "thinking": d["thinking"], "signature": d["signature"]})
        elif d.get("type") == "text":
            ac.append({"type": "text", "text": d["text"]})

    m2 = [
        {"role": "user", "content": [{"type": "text", "text": MSG}]},
        {"role": "assistant", "content": ac},
        {"role": "user", "content": [{"type": "text", "text": "Now about Mars."}]},
    ]
    with client.beta.messages.stream(
        betas=BETAS,
        model="claude-sonnet-4-6",
        max_tokens=8000,
        cache_control={"type": "ephemeral"},
        system=sys,
        tools=[CODE_EXEC],
        messages=m2,
        thinking={"type": "enabled", "budget_tokens": 2048},
        container=container,
    ) as s:
        r2 = s.get_final_message()
    u2 = r2.usage

    r1r = u1.cache_read_input_tokens or 0
    r1w = u1.cache_creation_input_tokens or 0
    r2r = u2.cache_read_input_tokens or 0
    r2w = u2.cache_creation_input_tokens or 0
    hit = "HIT" if r2r > r1r + 100 else "MISS"
    print(f"[{label:40s}] R1: read={r1r:>6} write={r1w:>6} | R2: read={r2r:>6} write={r2w:>6} | {hit}")


print("Test 1: container with empty skills (expected: HIT)")
test("empty skills", {"skills": []})

print("\nTest 2: container with custom skills (expected: HIT, actual: MISS)")
test("custom skills", {"skills": SKILLS})

Request IDs from our testing (with all 3 betas):

• Empty skills Turn 1: req_011CZrmGrt9icQRYZk43zYuG (write=35301)
• Empty skills Turn 2: req_011CZrmH1kTHygE588SePDwg (read=35301 - HIT)
• Custom skills Turn 1: req_011CZrhUg87qqzAC5uGD67GJ (write=37097)
• Custom skills Turn 2: req_011CZrhV5bVzxmFwvRYRAfvD (read=0 - MISS)