---
title: "List skills"
description: "List available skills (presets + user's custom). Returns {skills, total}."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: AI Gateway API › Skills

`GET /skills`

List available skills (presets + user's custom). Returns {skills, total}.

## Authentication

- `HTTPBearer`, http, header `Authorization`

## Query parameters

- `app_id` (`list_skills.query.app_id`; any of, optional) — App scope. Default: matches skills.app_ids plus global rows. With the X-Use-Taxonomy header: an app slug resolved through the category taxonomy (no global rows); an unknown slug 404s. None = no filter.
  - any of: `string`, `null`
- `category` (`list_skills.query.category`; any of, optional) — Filter by category. Default: skills.category string. With the X-Use-Taxonomy header: a categories.id UUID.
  - any of: `string`, `null`
- `is_active` (`list_skills.query.is_active`; any of, optional) — Filter by active flag.
  - any of: `boolean`, `null`
- `search` (`list_skills.query.search`; any of, optional) — ILIKE match on name or description.
  - any of: `string`, `null`
- `limit` (`list_skills.query.limit`; integer, optional)
  - min 1; max 200; default `50`
- `offset` (`list_skills.query.offset`; integer, optional)
  - min 0; default `0`

## Header parameters

- `X-Use-Taxonomy` (`list_skills.header.X-Use-Taxonomy`; boolean, optional) — When true, resolve app_id (as an app slug) and category (as a categories.id UUID) through the admin apps/categories taxonomy instead of the legacy app_ids array and category string. When absent/false, app_id and category use their legacy meanings.
  - default `false`
- `X-On-Behalf-Of` (`list_skills.header.X-On-Behalf-Of`; any of, optional)
  - any of: `string`, `null`
- `X-External-User-Id` (`list_skills.header.X-External-User-Id`; any of, optional)
  - any of: `string`, `null`
- `X-App-Id` (`list_skills.header.X-App-Id`; any of, optional)
  - any of: `string`, `null`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://truememory-api.mvstg.com/skills \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://truememory-api.mvstg.com/skills';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://truememory-api.mvstg.com/skills"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "skills": [
    {
      "id": "string",
      "user_id": "string",
      "app_ids": [
        "string"
      ],
      "key": "string",
      "name": "string",
      "description": "string",
      "prompt": "string",
      "category": "string",
      "categories": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "icon": "string",
      "argument_hint": "string",
      "allowed_tools": [
        "string"
      ],
      "metadata": {},
      "use_case": "string",
      "detection_patterns": [
        "string"
      ],
      "license": "string",
      "compatibility": "string",
      "is_preset": true,
      "is_active": true,
      "sort_order": 0,
      "forked_from_skill_id": "string",
      "usage_count": 0,
      "last_used_at": "2019-08-24T14:15:22Z",
      "parent_synced_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "app_id": "string"
    }
  ],
  "total": 0
}
```

- `skills` (`list_skills.response.200.skills`; array<object>, required)
  - `id` (`list_skills.response.200.skills.id`; string, required)
  - `user_id` (`list_skills.response.200.skills.user_id`; any of, required) — Owner user_id, NULL for presets.
    - any of: `string`, `null`
  - `app_ids` (`list_skills.response.200.skills.app_ids`; any of, required) — Apps this skill is assigned to. NULL means all apps (global/unscoped).
    - any of: `array<string>`, `null`
  - `key` (`list_skills.response.200.skills.key`; string, required)
  - `name` (`list_skills.response.200.skills.name`; string, required)
  - `description` (`list_skills.response.200.skills.description`; any of, required)
    - any of: `string`, `null`
  - `prompt` (`list_skills.response.200.skills.prompt`; string, required)
  - `category` (`list_skills.response.200.skills.category`; any of, required) — Freeform grouping label (legacy string). Distinct from `categories`.
    - any of: `string`, `null`
  - `icon` (`list_skills.response.200.skills.icon`; any of, required)
    - any of: `string`, `null`
  - `argument_hint` (`list_skills.response.200.skills.argument_hint`; any of, required)
    - any of: `string`, `null`
  - `allowed_tools` (`list_skills.response.200.skills.allowed_tools`; array<string>, required)
  - `metadata` (`list_skills.response.200.skills.metadata`; object, required)
  - `is_preset` (`list_skills.response.200.skills.is_preset`; boolean, required)
  - `is_active` (`list_skills.response.200.skills.is_active`; boolean, required)
  - `sort_order` (`list_skills.response.200.skills.sort_order`; integer, required)
  - `forked_from_skill_id` (`list_skills.response.200.skills.forked_from_skill_id`; any of, required)
    - any of: `string`, `null`
  - `usage_count` (`list_skills.response.200.skills.usage_count`; integer, required) — Global invocation count, bumped via POST /skills/{id}/usage.
  - `last_used_at` (`list_skills.response.200.skills.last_used_at`; any of, required) — When the skill was last invoked, NULL if never.
    - any of: `string`, `null`
  - `parent_synced_at` (`list_skills.response.200.skills.parent_synced_at`; any of, required) — For forks: the preset updated_at this fork is synced to. The fork is stale when its preset's updated_at is newer. NULL for non-forks.
    - any of: `string`, `null`
  - `created_at` (`list_skills.response.200.skills.created_at`; string, required)
    - format `date-time`
  - `updated_at` (`list_skills.response.200.skills.updated_at`; string, required)
    - format `date-time`
  - `app_id` (`list_skills.response.200.skills.app_id`; any of, required) — DEPRECATED, read app_ids instead. Legacy single-app scalar derived from app_ids for pre-multi-app consumers: the first app id, or null for all apps. Lossy for multi-app skills.
    - any of: `string`, `null`
  - `categories` (`list_skills.response.200.skills.categories`; array<object>, optional) — Category entities assigned via the registry. Returned by the list endpoints, the single-skill reads (user and admin) and PUT /admin/skills/{skill_id}/categories; omitted by writes.
    - `id` (`list_skills.response.200.skills.categories.id`; string, required)
    - `name` (`list_skills.response.200.skills.categories.name`; string, required)
  - `use_case` (`list_skills.response.200.skills.use_case`; any of, optional) — When this skill applies, in natural language. Read by skill selection.
    - any of: `string`, `null`
  - `detection_patterns` (`list_skills.response.200.skills.detection_patterns`; any of, optional) — Example utterances that should invoke this skill.
    - any of: `array<string>`, `null`
  - `license` (`list_skills.response.200.skills.license`; any of, optional) — SKILL.md `license`: a license name, or the file in the skill that holds it.
    - any of: `string`, `null`
  - `compatibility` (`list_skills.response.200.skills.compatibility`; any of, optional) — SKILL.md `compatibility`: what the skill needs to run (product, packages, network).
    - any of: `string`, `null`
- `total` (`list_skills.response.200.total`; integer, required) — Total rows matching the filters before LIMIT/OFFSET.

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`list_skills.response.422.detail`; array<object>, optional)
  - `loc` (`list_skills.response.422.detail.loc`; array<any of>, required)
    - any of: `string`, `integer`
  - `msg` (`list_skills.response.422.detail.msg`; string, required)
  - `type` (`list_skills.response.422.detail.type`; string, required)
  - `input` (`list_skills.response.422.detail.input`; unknown, optional)
  - `ctx` (`list_skills.response.422.detail.ctx`; object, optional)


Source: https://truememory-docs.mvstg.com/api/skills/list/index.md