Claude API Files And Documents

Own Claude Platform Files API lifecycle plans and PDF document request contracts. Produce a closed plan, validate it offline, and reject unsupported operations or unproven platform behavior. [DOC][CONFIG]

Boundary

Use this skill for:

• Files API upload, file_id reference, list, metadata retrieval, conditional download, and deletion. [DOC]
• Mapping PDF/text/image/other file MIME types to document, image, or container_upload blocks. [DOC]
• PDF inputs delivered as URL, base64, or Files API file_id, including request/page/format checks. [DOC]

Route elsewhere when the primary task is:

• Claude Platform text-editor operations: claude-api-client-tools; document authoring or documentation-system design: documentation-architecture; [CONFIG]
• Claude Platform web-fetch server tools: claude-api-server-tools; general web research: web-research; [CONFIG]
• generic blob/object storage, buckets, backups, or retention architecture: cloud-native-architecture; [CONFIG]
• tool naming/schema ergonomics: tool-use-design; [CONFIG]
• privacy policy, classification, or retention governance: data-privacy-governance. [CONFIG]
• token budgets, cache, context editing, compaction, or context fit policy: claude-api-context-management. [CONFIG]

A PDF URL inside a Messages document source is a document input, not a general-purpose web fetch. Files API storage is an API-specific create-once/use-many surface, not a generic storage service. [DOC][INFERENCIA]

Contract

• Acceptance: return a source-grounded file/document plan whose lifecycle, source type, content block, platform, beta, limits, and failure paths pass scripts/validate_file_document_plan.py. [CONFIG]
• Evidence: use only evidence IDs files and pdf-support; field-level claims must resolve through references/official-source-map.md. [CONFIG]
• Fail closed: reject unknown keys, operations, platforms, source types, API surfaces, MIME/block combinations, missing beta declarations, impossible download states, and violated PDF limits. [CÓDIGO]
• Limits: do not call a live API, fetch a PDF, upload content, edit a file, or implement generic storage. The validator checks plans only. [CONFIG]
• Separation: a producer creates the plan; a different verifier runs the schema, checklist, fixtures, and gate. [CONFIG]

Required Inputs

• Intent: files_lifecycle or pdf_analysis. [CONFIG]
• Target platform and API surface. [DOC][CONFIG]
• For Files API: operation order, filename, MIME type, size, origin, downloadability, and file_id placeholder or existing ID. [DOC][CONFIG]
• For PDF: source type, total payload size, page count, context-window size, encryption/password state, analysis mode, citations state, and content order. [DOC][CONFIG]
• Explicit residual gaps for platform-specific request limits, context fit, or adjacent container execution behavior. [INFERENCIA]

Procedure

1. Load references/official-source-map.md; do not import claims from any other corpus. [CONFIG]
2. Route with prompts/meta.md; reject text editing, web fetch, and generic storage false positives. [CONFIG]
3. Apply references/files-api-contract.md for Files API availability, beta, lifecycle, MIME/block mapping, limits, downloadability, and errors. [DOC]
4. Apply references/pdf-contract.md for source/platform compatibility, PDF format, request/page limits, visual mode, and recommendations. [DOC]
5. Start from templates/file-document-plan.json and keep the plan free of file bytes, base64 payloads, credentials, and fetched content. [CONFIG]
6. Have the producer emit the plan and evidence ledger; then hand it to the separate verifier. [CONFIG]
7. Run python3 scripts/validate_file_document_plan.py --plan <plan.json> and bash scripts/check.sh. [CÓDIGO]
8. Return the decision, typed issues/warnings, evidence IDs, and residual coverage_gap entries. [CONFIG]

Core Rules

• Files API use requires files-api-2025-04-14; SDK file methods may add the beta header automatically, while Messages requests that reference a file still require the beta declaration. [DOC]
• Files API is supported only on the platform variants proven in the local files source; reject file-backed plans on unsupported variants. [DOC]
• Uploaded files are immutable, cannot be renamed, persist until deletion, are workspace-scoped, and cannot be recovered after deletion. API inaccessibility follows shortly after deletion, but active Messages/tool uses may retain access until their lifecycle ends; route retention/ZDR approval to data-privacy-governance. [DOC][CONFIG]
• A client-uploaded file has downloadable: false; only a generated file whose metadata says downloadable: true may be downloaded. [DOC]
• Enforce the documented 500 MB per-file upload limit, 500 GB organization storage limit as an external precondition, filename constraints, and MIME/block compatibility. [DOC]
• A valid upload size does not prove a file fits a Messages context window. Keep context fit explicit for document use. [DOC][INFERENCIA]
• PDF sources are url, base64, or Files API file; platform support differs, so source/platform compatibility is mandatory. [DOC]
• PDF plans must use a document block with application/pdf, standard unencrypted/unpassworded PDF, no more than 32 MB total request payload, and no more than 600 pages; requests below a 1M-token context window are capped at 100 pages. [DOC]
• The 32 MB request limit varies by platform. Non-Claude-API plans must declare platform_payload_limit_unverified until that platform's active limit is independently confirmed. [DOC][coverage_gap]
• Dense PDFs may exhaust context before page/request limits. Record pdf_context_fit_unverified unless the caller supplies separate context-fit evidence. [DOC][coverage_gap]
• In Bedrock Converse, visual PDF analysis requires citations; without citations, only text extraction is supported. [DOC]
• For a three-page Bedrock Converse PDF, treat roughly 1,000 tokens as the text-only fallback estimate and roughly 7,000 as the visual-mode estimate; never quote either without mode and citations context. [DOC]
• Place PDF document blocks before instruction text as a performance recommendation; report a warning rather than treating order as a protocol error. [DOC][CÓDIGO]
• container_upload validates only the Files API block mapping here; execution-tool semantics remain container_execution_contract_out_of_scope. [DOC][coverage_gap]

Outputs Expected

• Closed JSON plan conforming to assets/file-document-plan.schema.json. [CONFIG]
• Producer evidence ledger using only files and pdf-support. [CONFIG]
• Verifier report with accept or reject, typed findings, warnings, and coverage_gap values. [CÓDIGO]
• Offline validation evidence from scripts/check.sh; no API key, network request, upload, or billable call. [CONFIG]

Resources

• agents/producer.md - source-grounded plan producer.
• agents/verifier.md - independent fail-closed verifier.
• references/official-source-map.md - the two official URLs, normalized corpus paths, and hashes.
• references/files-api-contract.md - Files API lifecycle, blocks, limits, and errors.
• references/pdf-contract.md - PDF sources, platforms, request limits, and visual-mode rules.
• references/validator-contract.md - closed plan shape, issue codes, and CLI behavior.
• assets/file-document-plan.schema.json - portable plan schema.
• assets/review-checklist.md - producer/verifier acceptance checklist.
• examples/valid-files-lifecycle.json - valid create-once/use-many lifecycle example.
• examples/valid-pdf-support.json - valid file-backed PDF example.
• examples/invalid-boundary.json - invalid editor/fetch/generic-storage example.
• scripts/validate_file_document_plan.py - stdlib-only fail-closed validator.
• scripts/check.sh - deterministic packet, eval, fixture, and unittest gate.

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · scripts/ automatización local · assets/ recursos estáticos.