Manage Agent Skills

This guide uses the V4 Agent Memory API. You need access to that API and a project that is entitled to Agent Memory. An Agent can use an imported Skill only after the candidate is admitted. The import operation accepts a portable ZIP archive and returns a Task for the import.

Export a generated Skill version with POST /api/v4/agents/{agent_uuid}/skills/{skill_uuid}/versions/{version}/export. After the Task succeeds, download the archive with GET /api/v4/agents/{agent_uuid}/skills/{skill_uuid}/versions/{version}/export/{task_uuid}.

The archive contains a portable copy of the procedure. The source Skill retains its evidence. The copy omits the evidence and its citations and has a customer_authored origin. Approval of the copy does not establish empirical verification in the destination Agent.

Send the archive to POST /api/v4/agents/{agent_uuid}/skills/import with an Idempotency-Key header. Poll the returned Task at GET /api/v4/tasks/{task_uuid} until its status is succeeded. The completed Task includes the imported Skill’s UUID in result.skill_uuid.

Use that UUID to read the candidate with GET /api/v4/agents/{agent_uuid}/skills/{skill_uuid}. To approve it, send POST /api/v4/agents/{agent_uuid}/skills/{skill_uuid}/approve with a new Idempotency-Key header. Set the body to {"expected_version": 1} if the candidate’s current_version is 1. Use the candidate’s actual current_version for other versions. Confirm that the Skill is active and searchable before you include it in retrieval.

Search an Agent’s active Skills with POST /api/v4/agents/{agent_uuid}/skills/search. Read a selected Skill with GET /api/v4/agents/{agent_uuid}/skills/{skill_uuid} or its version endpoint. These retrieval requests use the Agent UUID in the URL. They do not transfer a Skill to another Agent.

Import does not approve a Skill. The Task result does not include the archive, the import principal, or the internal bindings.