Creates a reusable skill.

POST

https://api.awork.com/api/v1/agents/skills

POST

/api/v1/agents/skills

curl -X POST https://api.awork.com/api/v1/agents/skills \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "instructions": "string"
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "createdOn": "2024-01-15T09:30:00Z",
  "updatedOn": "2024-01-15T09:30:00Z",
  "key": "string",
  "name": "string",
  "description": "string",
  "instructions": "string",
  "instructionsSource": "string",
  "type": "user",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "accessLevel": "read",
  "isOwner": true,
  "hasAdminAccessOnly": false,
  "workspaceAccessLevel": "read",
  "linkedAgentCount": 1,
  "metadata": "string",
  "hasFiles": true,
  "secretRequirements": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "envVarName": "string",
      "description": "string",
      "scope": "workspace",
      "isRequired": true,
      "hasValue": true
    }
  ]
}

Creates a user-owned skill and enables it when the creator may configure the awork Agent.

Required Permissions

Any authenticated user.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

The request payload.

instructionsstringRequired>=1 character

The Markdown instruction body from SKILL.md.

keystring or nullOptional<=100 characters

The stable key used to reference the skill.

namestring or nullOptional<=255 characters

The name shown in the skill library.

descriptionstring or nullOptional

A short explanation of what the skill does.

instructionsSourcestring or nullOptional

The source from which the instructions were created.

metadatastring or nullOptional

The skill frontmatter as a JSON object.

Response

idstringOptionalformat: "uuid"

The skill identifier.

createdBystringOptionalformat: "uuid"

The user who created the skill.

createdOnstringOptionalformat: "date-time"

When the skill was created.

updatedOnstring or nullOptionalformat: "date-time"

When the skill was last updated.

keystring or nullOptional

The stable key used to reference the skill.

namestring or nullOptional

The name shown in the skill library.

descriptionstring or nullOptional

A short explanation of what the skill does.

instructionsstring or nullOptional

The Markdown instruction body from SKILL.md.

instructionsSourcestring or nullOptional

The source from which the instructions were created.

typeenumOptional

The ownership type.

Allowed values:

userIdstring or nullOptionalformat: "uuid"

The owning user for a user-owned skill.

agentIdstring or nullOptionalformat: "uuid"

The owning agent for an agent-owned skill.

accessLevelenumOptional

The requesting user's resolved access level.

Allowed values:

isOwnerbooleanOptional

Whether the requesting user owns the skill.

hasAdminAccessOnlybooleanOptional

Whether the skill is visible only through workspace administration access.

workspaceAccessLevelenum or nullOptional

The workspace-wide access level.

Allowed values:

linkedAgentCountintegerOptional

The number of linked agents.

metadatastring or nullOptional

The skill frontmatter as a JSON object.

hasFilesbooleanOptional

Whether the skill includes bundled files.

secretRequirementslist of objects or nullOptional

The secrets that the skill declares.

Errors

400

Bad Request Error

401

Unauthorized Error