Create skill

Create a skill. Defaults to Public (account) privacy with an initial invocation assignment to the API key’s teamspace; creation and assignment are atomic, and the returned scope remains account. Pass scope: user to create a Private skill without an initial assignment. Public slash keys must not collide with a built-in.

POST /skills

Create skill

Python

import requests

url = "https://api.datagrid.com/v1/skills"

payload = {
    "name": "<string>",
    "slash_key": "<string>",
    "instructions": "<string>",
    "description": "<string>",
    "required_tools": ["<string>"],
    "preferred_tools": ["<string>"],
    "enabled": True,
    "scope": "account"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

201

{
  "object": "skill",
  "id": "<string>",
  "scope": "user",
  "category": "document_analysis",
  "slash_key": "<string>",
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "required_tools": [
    "<string>"
  ],
  "preferred_tools": [
    "<string>"
  ],
  "enabled": true,
  "account_id": "<string>",
  "builtin_key": "<string>",
  "promoted_at": "2023-11-07T05:31:56Z",
  "creator_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

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

Body

application/json

name · string · required

Display name of the skill.

Maximum string length: 255

slash_key · string · required

The slash command key (e.g. budget-check, 3d-review). Must use lowercase letters, digits, and single dashes, start and end with a letter or digit, and be unique within the scope.

Required string length: 1 - 64

Pattern: ^(?!.*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$

instructions · string · required

The full instructions / system prompt for this skill.

category · enum<string> · required

Category bucket.

Available options: document_analysis, construction_project_management, financial_analysis, estimation, quality_and_safety, scheduling, contracts_and_legal, data_and_reporting, research, communication, general_productivity

description · string | null

Short description. When omitted, an AI-generated description is produced from the instructions.

Maximum string length: 1000

required_tools · string[] | null

Tool identifiers required by this skill.

preferred_tools · string[] | null

Tool identifiers preferred by this skill.

enabled · boolean | null · default: true

Whether the skill is active. Defaults to true.

scope · enum<string> | null · default: account

Ownership of the new skill. Defaults to account (company-owned). Pass user for a private skill that can later be promoted.

Available options: user, account

Response

201

application/json

Created skill

object · enum<string> · required

The object type, always 'skill'.

Available options: skill

id · string · required

Unique identifier for the skill.

scope · enum<string> · required

Privacy scope. user = Private (author only), account = Public within the company, teamspace = deprecated legacy Public value retained only for compatibility, and builtin = global default. New skills never use teamspace; changing its privacy or assignments normalizes it.

Available options: user, account, teamspace, builtin

category · enum<string> · required

Category bucket for grouping in the skill picker.

Available options: document_analysis, construction_project_management, financial_analysis, estimation, quality_and_safety, scheduling, contracts_and_legal, data_and_reporting, research, communication, general_productivity

slash_key · string · required

The slash command key used to invoke this skill (e.g. budget-check).

name · string · required

Display name of the skill.

description · string · required

Short description shown in the skill picker.

instructions · string · required

The full instructions / system prompt for this skill.

required_tools · string[] · required

Tool identifiers that this skill requires to function.

preferred_tools · string[] · required

Tool identifiers that this skill works best with.

enabled · boolean · required

Whether the skill is active and available for selection. For a built-in skill, false when your company disabled it.

account_id · string | null · required

The account (company) that owns this skill. null for user-scope and builtin skills.

builtin_key · string | null · required

For built-in skills and company copies of them: the identifier of the built-in. null for user-authored skills.

promoted_at · string<date-time> | null · required

ISO timestamp when this skill was promoted to company scope. null for user-scope skills.

creator_id · string | null · required

ID of the user who created this skill. null for built-in skills that have never been edited.

created_at · string<date-time> · required

ISO timestamp when this skill was created.

updated_at · string<date-time> · required

ISO timestamp when this skill was last updated.