Skip to content
shiftagent Integration API

List a repository's skills.

GET
/repositories/{repository_id}/skills
 
curl --request GET \
  --url 'https://shiftagent.example.com/repositories/example/skills?limit=20&refresh=false' \
  --header 'Authorization: Bearer <token>'

Lists the skills the repository dictates. Served from the sync cache by default; pass ?refresh=true to force a fresh git read first (slower, but guaranteed current — equivalent to a synchronous syncRepository followed by the cached read).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
repository_id
required
string
/^rep_[A-Za-z0-9]+$/

Internal repository ID.

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 20 >= 1 <= 100

Page size (1–100).

starting_after
string

Cursor: return items after this object ID (forward pagination). Use the id of the last item of the previous page.

ending_before
string

Cursor: return items before this object ID (backward pagination). Mutually exclusive with starting_after.

refresh
boolean

When true, re-scan the repository before answering instead of serving the sync cache.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A page of skills.

Media type application/json
object
object
required

Envelope discriminator.

string
Allowed value: list
data
required

The page of items.

Array
has_more
required

Whether more items exist beyond this page.

boolean
next_cursor

Opaque cursor for the next page (pass as starting_after). Null when has_more is false.

string | null
data
required
Array<object>

Capability unit dictated by a repository — discovered by sync or added manually.

object
object
required
string
Allowed value: skill
id
required
string
/^skl_[A-Za-z0-9]+$/
repository_id
required
string
/^rep_[A-Za-z0-9]+$/
name
required

Slug, unique per repository.

string
<= 128 characters /^[a-z0-9][a-z0-9-]*$/
description
required

What the skill does (from its manifest).

string | null
version
required

Manifest version.

string | null
path
required

Location of the manifest inside the repository.

string | null
source
required

discovered — found by repository sync (pruned if it disappears); manual — added via createRepositorySkill (survives re-syncs).

string
Allowed values: discovered manual
metadata
required

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object
<= 50 properties
key
additional properties
string
<= 500 characters
created_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
updated_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
Examples
Example field_ops_skills

Skills discovered in the field-ops repository

{
  "object": "list",
  "data": [
    {
      "object": "skill",
      "id": "skl_01hzx8dispatch",
      "repository_id": "rep_01hzx8fieldops",
      "name": "dispatch-scheduler",
      "description": "Plan and assign field-technician dispatch schedules.",
      "version": "1.2.0",
      "path": ".claude/skills/dispatch-scheduler/SKILL.md",
      "source": "discovered",
      "metadata": {},
      "created_at": "2026-07-02T09:32:00Z",
      "updated_at": "2026-07-02T09:32:00Z"
    },
    {
      "object": "skill",
      "id": "skl_01hzx8invoice",
      "repository_id": "rep_01hzx8fieldops",
      "name": "invoice-lookup",
      "description": "Retrieve and explain customer invoices.",
      "version": "1.0.3",
      "path": ".claude/skills/invoice-lookup/SKILL.md",
      "source": "discovered",
      "metadata": {},
      "created_at": "2026-07-02T09:32:00Z",
      "updated_at": "2026-07-02T09:32:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

400

Section titled “400 ”

Bad request — malformed body/parameters or an invalid parameter combination (e.g. neither or both of user_id/tenant_id on listConversations, or both pagination cursors).

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example bad_request

Invalid parameter combination

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Invalid request",
  "status": 400,
  "detail": "Exactly one of user_id or tenant_id is required.",
  "request_id": "req_01hzx8bad001"
}

401

Section titled “401 ”

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}

404

Section titled “404 ”

Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example not_found

Unknown resource

{
  "type": "https://shiftagent.example.com/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No tenant with external_id acme:tenant:999999.",
  "request_id": "req_01hzx8nf001"
}