Manage Skills

In this tutorial you will create a skill, publish a versioned release, and attach it to an agent. Skills are reusable capabilities that define what an agent can do.

Prerequisites

• A Chainabit account with a valid access token
• curl available in your terminal
• An existing agent (see Create an AI Agent)

Set your environment variables:

export TOKEN="your-access-token"

---

Skill Structure

A skill can have multiple versions. Each agent references a specific version, so you can roll out updates gradually.

---

Step 1: Create a Skill

Define a new skill with its metadata:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Activity Summarizer",
    "description": "Generates natural-language summaries from activity completion data.",
    "category": "analytics"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/skills`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Activity Summarizer',
    description:
      'Generates natural-language summaries from activity completion data.',
    category: 'analytics',
  }),
});
const data = await res.json();
console.log(data);

Python

import requests

res = requests.post(
    f"{BASE}/agents/skills",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Activity Summarizer",
        "description": "Generates natural-language summaries from activity completion data.",
        "category": "analytics",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "skill_01HQA...",
    "name": "Activity Summarizer",
    "description": "Generates natural-language summaries from activity completion data.",
    "category": "analytics",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Save the skill ID:

export SKILL_ID="skill_01HQA..."

---

Step 2: Create a Skill Version

Publish a versioned release with the skill's implementation details:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/skill-versions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skillId": "'"$SKILL_ID"'",
    "version": "1.0.0",
    "instructions": "Given a list of bit completions, produce a summary paragraph highlighting streaks, missed days, and overall progress.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "bitIds": { "type": "array", "items": { "type": "string" } },
        "dateRange": { "type": "string" }
      },
      "required": ["bitIds"]
    },
    "status": "published"
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/agents/skill-versions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    skillId: SKILL_ID,
    version: '1.0.0',
    instructions:
      'Given a list of bit completions, produce a summary paragraph highlighting streaks, missed days, and overall progress.',
    inputSchema: {
      type: 'object',
      properties: {
        bitIds: { type: 'array', items: { type: 'string' } },
        dateRange: { type: 'string' },
      },
      required: ['bitIds'],
    },
    status: 'published',
  }),
});
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/agents/skill-versions",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "skillId": SKILL_ID,
        "version": "1.0.0",
        "instructions": "Given a list of bit completions, produce a summary paragraph highlighting streaks, missed days, and overall progress.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "bitIds": {"type": "array", "items": {"type": "string"}},
                "dateRange": {"type": "string"},
            },
            "required": ["bitIds"],
        },
        "status": "published",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "sv_01HQB...",
    "skillId": "skill_01HQA...",
    "version": "1.0.0",
    "status": "published",
    "createdAt": "2026-03-17T10:01:00.000Z"
  }
}

Save the skill version ID:

export SKILL_VERSION_ID="sv_01HQB..."

---

Step 3: Attach the Skill to an Agent

Link the published skill version to an existing agent:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/agents/definitions/$AGENT_ID/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skillVersionId": "'"$SKILL_VERSION_ID"'"
  }'

JavaScript

const res = await fetch(
  `https://api.chainabit.com/api/v1/agents/definitions/${AGENT_ID}/skills`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      skillVersionId: SKILL_VERSION_ID,
    }),
  },
);
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/agents/definitions/{AGENT_ID}/skills",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={"skillVersionId": SKILL_VERSION_ID},
)
print(res.json())

Response:

{
  "data": {
    "agentId": "agent_01HQA...",
    "skillVersionId": "sv_01HQB...",
    "attachedAt": "2026-03-17T10:02:00.000Z"
  }
}

---

Step 4: List Skills on an Agent

Verify which skills are attached:

cURL

curl -s "https://api.chainabit.com/api/v1/agents/definitions/$AGENT_ID/skills" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const res = await fetch(
  `https://api.chainabit.com/api/v1/agents/definitions/${AGENT_ID}/skills`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const data = await res.json();
console.log(data);

Python

res = requests.get(
    f"{BASE}/agents/definitions/{AGENT_ID}/skills",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(res.json())

---

Summary

In this tutorial you:

1. Created a skill definition with metadata
2. Published a skill version with instructions and an input schema
3. Attached the skill to an agent
4. Listed the skills on an agent

Next Steps

• Create an AI Agent if you have not set up an agent yet
• Chain Triggers to run chains (workflows) that use skills
• Agents API Reference for the complete endpoint documentation