---
title: "Attach or detach agent skills"
method: PATCH
path: "/agents/{agent_id}/skills"
tags: ["Agents"]
---

# Attach or detach agent skills

`PATCH /agents/{agent_id}/skills`

Attach and/or detach skills on an agent using deltas. This is **not** a replace-list: skills you don't mention are left untouched.

- The operation is idempotent. Re-attaching a skill that's already attached (or detaching one that isn't) is reported under `already_attached` / `already_detached` rather than failing.
- A skill ID may not appear in both `attach` and `detach`.
- Up to 100 unique skill IDs total (`attach` + `detach`) per request.
- Attaching requires `INVOKE` permission on the skill. Detaching is permissive so stale attachments can always be removed.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `attach` string[] — Skill IDs to attach. Ignored if already attached.
  - `detach` string[] — Skill IDs to detach. Ignored if not attached.

## Response `200`

The resulting skill set plus what this request changed.

- object
  - `agent_id` string
  - `skill_ids` string[] — Full set of skills attached to the agent after this request.
  - `attached` string[] — Skills newly attached by this request.
  - `detached` string[] — Skills newly detached by this request.
  - `already_attached` string[] — Requested attaches that were already attached (no-op).
  - `already_detached` string[] — Requested detaches that weren't attached (no-op).

## Other responses

- `400` — Invalid request — e.g. an ID appears in both `attach` and `detach`, more than 100 unique IDs, or a skill to attach doesn't exist or isn't active (offending IDs returned in `error.details.skill_ids`).
- `401` — Unauthorized — missing or invalid API key.
- `403` — Forbidden — the caller lacks update access to the agent, or lacks `INVOKE` permission on a skill being attached (offending IDs in `error.details.skill_ids`).
- `404` — Agent not found.
- `500` — Internal server error.

---

[API](https://skmtc.dev/gumloop/apis/public-api.md) · [All operations](https://skmtc.dev/gumloop/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumloop/public-api/revisions/115f2d6ce387/schema)