Library

ChatGPT Library

Use this as the top-level router for persistent ChatGPT Library files. Ground the target in Library, choose one content-access route, and preserve Library identity through every local edit and writeback.

The Library first-party app, connector_openai_library, owns authenticated Library operations:

• list, search, read, and find inspect Library content.
• prepare_materialize makes resolved Library files available to local tools.
• create_library_file, replace_library_file, and manage_library write or organize Library content.
• share grants or revokes access; follow its current app-provided description and schema.
• When surfaced, prepare_uploads and finalize_uploads handle prepared uploads.
• App-only file @ mention search resolves selected Library items.

The runtime supplies the schemas and decides which tools are available. This skill does not expose tools or a local MCP server.

Workflow

1. Ground the target.
   • Decode a selected Library @ mention and reuse its identifiers.
   • Use search for a filename, title, description, or content query.
   • Use list for recent files, folders, or inventory.
   • If the user supplied a local path or explicitly said the file is local, stay with local tools.
2. Choose one access route.
   • Use read when Library can supply the content the task needs.
   • Use find for literal or regex matching inside known files.
   • Materialize when editing, scripts, visual inspection, generation, byte comparison, or another local tool needs file bytes.
3. Preserve identity when writing.
   • Create only when no Library identity exists or the user wants a copy.
   • Replace the same library_file_id after editing an existing item.
   • Use manage_library for folders, node changes, deletion, and restore.

Use Current Helpers

1. Before downloading, remove any downloaded copies of helpers from previous runs in the scoped workspace folder
2. Fetch the helper and all its companion files from the current Library skill source into one new private directory.
3. Reuse the downloaded helpers for every call and retry within this request or run.

Routing Rules

For list, set limit to at most 200. For search, use the canonical request shape {"search_query":[{"q":"quarterly revenue"}],"top_k":5}. search_query must be an array of one to five objects, even for one search. Put search_title_only only inside a search_query object. Never send top-level query, queries, q, search_title_only, or limit; use top-level top_k from 1 to 100.

For Library intent, search Library before the local workspace unless the user supplied a local path or said the file is local. Once routed to Library, do not scan the workspace or prior conversations for the same target. Failure to resolve a Library item is not evidence that it is local.

Read Library Content

Prefer structuredContent; parse a JSON text block only when it is unavailable. Use returned identifiers, filenames, versions, and paths exactly. For follow-up read or find, prefer the returned library_file_id, falling back to file_id or id. Never use a search result_id as a file reference. For read, put that identifier in read[i].ref_id:
{"read":[{"ref_id":"<returned library_file_id>"}]}.
The top-level read array must contain 1–5 items; do not send the identifier at the top level.

Batch independent read and find items when possible. Use read after search for content claims, even with snippets; use find only after candidate resolution.

Read evidence-and-citations.md for selected @ mentions, image-search metadata, post-mutation search limits, result handling, and citations.

Classify New Files

For new files, set library_artifact_type when supported:

• image_gen: images generated by imagegen only.
• image: other generated images.
• report, sheet, slides: generated documents/reports, spreadsheets, or presentations.
• other: user imports, unknown generation history, or anything else.

Classify by generation history, not filename, extension, or MIME type. create_library_file uses one type per call; prepared uploads use one per file. Omit the field for replacements or when the upload tool or helper lacks support.

Write One Local File

Use this fast path for one confirmed local file under about 50 MiB. Reuse validation already completed while producing or editing the artifact. Do not add another content inspection solely because the file is being saved to Library.

• For a new item, call create_library_file(file=...) with the absolute local path. On success, invoke this skill's scripts/library_file_transfer.py with python3, the apply-xattrs subcommand, the original local path, and the returned library_file_id. Send the complete xattrs array from the create result (or []) as JSON on stdin, as shown below. When using code mode (for example, functions.exec), call create_library_file and run the metadata helper within the same invocation, without returning to the model between them.
• For an existing item, resolve its Library identity and use the current local working file when it already contains the intended result. Do not materialize over that file. Materialize if needed; apply missing edits and validate once. Replace owned files using replace_library_file(file=...) with the same library_file_id. Shared stored files always use library_upload.py, even without prepared tools. Shared writing blocks also use library_upload.py, the bundled prepared-upload helper; convert their decimal version_id to the integer expected_current_version.
• An editor's new output path is still a replacement for the same Library item. Create only when no Library identity exists or the user wants a separate copy.
• Pass expected_current_version when a concrete version was retained. Never invent a version or remove the guard to resolve a conflict.

After create or replace, inspect the returned result. Use its filename and Library path as authoritative, and keep its exact library_file_id, file_id, version, and original local path together. Do not read the file back merely to confirm a successful write unless exact verification is required.

Privately persist the returned xattrs and Library identity in one helper call; do not add a separate progress message. The helper form is apply-xattrs PATH LIBRARY_FILE_ID, and both positional arguments are required:

skill_md_path="<absolute path of this SKILL.md>"
transfer_helper_path="$(dirname "$skill_md_path")/scripts/library_file_transfer.py"
python3 "$transfer_helper_path" \
  apply-xattrs "$local_path" "$library_file_id" <<'JSON'
<complete returned xattrs array, or []>
JSON

Inspect the helper result before finishing; do not claim that local identity was persisted if it failed. Read writeback-and-conflicts.md for direct create batches, version conflicts, or detailed result correlation.