Skills API Overview

Programmatically create, import, and manage Skills in your ajan workspace

The Skills API lets you manage Skills programmatically. Use it to sync Skills from a repository, inspect stored files, create reusable instruction sets, attach accessible integrations, and import SKILL.md files or zip archives.

Base URL

https://api.ajan.io

API Key Scope

All Skills API endpoints require an API key with the SKILL_API scope.

Available Endpoints

Method	Endpoint	Description
`GET`	`/skills/v1`	List Skills
`POST`	`/skills/v1`	Create a Skill
`GET`	`/skills/v1/{skillId}`	Get a Skill
`GET`	`/skills/v1/{skillId}/files`	Get a Skill file
`PATCH`	`/skills/v1/{skillId}`	Update a Skill
`DELETE`	`/skills/v1/{skillId}`	Delete a Skill
`POST`	`/skills/v1/import`	Import a Skill

Skill Object

Skills API responses use the same Skill object across endpoints:

typescript

{
  id: string;
  name: string;
  slug: string;
  description: string;
  instructions: string;
  integrationIds: string[];
  createdAt: string;
  updatedAt: string;
}

Get Skill also returns a files array with stored file metadata. List, create, and update responses do not include files.

Supported Skill Types

The API only manages Skills that users create in the workspace. System Skills, templates, and Skill Packs are not returned or modified through these endpoints.

For item endpoints, use the Skill id. The slug field is supported as a list filter and as the upsert key for imports, but reads, updates, and deletes use skillId.

Permissions

Requests use the key owner for permissions and access:

Action	Required access
List or get Skills, including files	Viewer access to the Skill
Create Skills or create through import	`createSkills` workspace permission
Update Skills or upsert through import	Editor access to the Skill
Delete Skills	Owner access to the Skill, or admin access

If you attach integrations with integrationIds, each integration must be enabled in your workspace.

Skill visibility

A workspace API key can list and get Skills it created, Skills shared with the workspace, and Skills a workspace admin shared with that key. A workspace admin grants that access in Share.

Rate Limits

The Skills API follows standard API rate limits. If you exceed the limit, you'll receive a 429 response. Wait and retry with exponential backoff.