curl -X GET "http://kaman.ai/agent/api/skills?status=active&limit=10&offset=0" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "skills": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_id": "42",
      "name": "SQL Query Best Practices",
      "slug": "sql-query-best-practices",
      "description": "Guidelines for writing efficient and safe SQL queries",
      "version": 1,
      "content": "When writing SQL queries, always use parameterized queries to prevent injection...",
      "content_tokens": 256,
      "trigger_keywords": ["sql", "query", "database"],
      "task_types": ["data-query", "database"],
      "domains": ["engineering", "data"],
      "tools": ["executeSQL", "queryDatabase"],
      "source_type": "manual",
      "usage_count": 15,
      "success_count": 12,
      "failure_count": 3,
      "status": "active",
      "created_at": "2026-02-10T08:00:00.000Z",
      "updated_at": "2026-02-15T14:30:00.000Z",
      "last_used_at": "2026-02-15T14:30:00.000Z",
      "supporting_files": [],
      "is_marketplace": false,
      "is_published": false,
      "author": null
    }
  ],
  "totalCount": 1
}

curl -X POST "http://kaman.ai/agent/api/skills/search" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to write safe SQL queries",
    "limit": 5,
    "domains": ["engineering"]
  }'

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "SQL Query Best Practices",
    "slug": "sql-query-best-practices",
    "description": "Guidelines for writing efficient and safe SQL queries",
    "content": "When writing SQL queries, always use parameterized queries...",
    "trigger_keywords": ["sql", "query", "database"],
    "domains": ["engineering", "data"],
    "status": "active",
    "similarity": 0.87
  }
]

curl -X GET "http://kaman.ai/agent/api/skills/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_id": "42",
  "name": "SQL Query Best Practices",
  "slug": "sql-query-best-practices",
  "description": "Guidelines for writing efficient and safe SQL queries",
  "version": 1,
  "content": "When writing SQL queries, always use parameterized queries...",
  "content_tokens": 256,
  "trigger_keywords": ["sql", "query", "database"],
  "task_types": ["data-query", "database"],
  "domains": ["engineering", "data"],
  "tools": ["executeSQL", "queryDatabase"],
  "source_type": "manual",
  "source_session_id": null,
  "parent_skill_id": null,
  "usage_count": 15,
  "success_count": 12,
  "failure_count": 3,
  "status": "active",
  "created_at": "2026-02-10T08:00:00.000Z",
  "updated_at": "2026-02-15T14:30:00.000Z",
  "last_used_at": "2026-02-15T14:30:00.000Z",
  "supporting_files": [],
  "marketplace_plugin_id": null,
  "is_marketplace": false,
  "is_published": false,
  "author": null
}

curl -X POST "http://kaman.ai/agent/api/skills" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SQL Query Best Practices",
    "description": "Guidelines for writing efficient and safe SQL queries",
    "content": "When writing SQL queries:\n1. Always use parameterized queries\n2. Add LIMIT clauses to prevent runaway queries\n3. Use indexes on frequently filtered columns",
    "trigger_keywords": ["sql", "query", "database"],
    "task_types": ["data-query"],
    "domains": ["engineering", "data"],
    "tools": ["executeSQL"]
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_id": "42",
  "name": "SQL Query Best Practices",
  "slug": "sql-query-best-practices",
  "description": "Guidelines for writing efficient and safe SQL queries",
  "version": 1,
  "content": "When writing SQL queries:\n1. Always use parameterized queries\n2. Add LIMIT clauses to prevent runaway queries\n3. Use indexes on frequently filtered columns",
  "content_tokens": 41,
  "trigger_keywords": ["sql", "query", "database"],
  "task_types": ["data-query"],
  "domains": ["engineering", "data"],
  "tools": ["executeSQL"],
  "source_type": "manual",
  "usage_count": 0,
  "success_count": 0,
  "failure_count": 0,
  "status": "active",
  "supporting_files": [],
  "is_marketplace": false,
  "is_published": false,
  "created_at": "2026-02-17T10:00:00.000Z",
  "updated_at": "2026-02-17T10:00:00.000Z"
}

curl -X PUT "http://kaman.ai/agent/api/skills/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated SQL best practices:\n1. Always use parameterized queries\n2. Add LIMIT clauses\n3. Use CTEs for readability\n4. Avoid SELECT *",
    "trigger_keywords": ["sql", "query", "database", "optimization"]
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "SQL Query Best Practices",
  "content": "Updated SQL best practices:\n1. Always use parameterized queries\n2. Add LIMIT clauses\n3. Use CTEs for readability\n4. Avoid SELECT *",
  "trigger_keywords": ["sql", "query", "database", "optimization"],
  "updated_at": "2026-02-17T12:00:00.000Z"
}

curl -X DELETE "http://kaman.ai/agent/api/skills/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "message": "Skill deprecated"
}

curl -X POST "http://kaman.ai/agent/api/skills/a1b2c3d4-e5f6-7890-abcd-ef1234567890/publish" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "message": "Skill published to marketplace",
  "skillId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "name": "SQL Query Best Practices",
  "description": "Guidelines for writing efficient and safe SQL queries",
  "type": "skill",
  "published": true,
  "isDraft": false,
  "status": "published",
  "version": "1.0.0",
  "clientId": 42,
  "userId": "user-uuid",
  "author": "Jane Doe",
  "category": "engineering",
  "skill_manifest": {
    "content": "When writing SQL queries...",
    "triggerKeywords": ["sql", "query", "database"],
    "taskTypes": ["data-query"],
    "domains": ["engineering", "data"],
    "tools": ["executeSQL"],
    "supporting_files": []
  },
  "manifest": {
    "skill_manifest": { "..." : "..." }
  }
}

curl -X POST "http://kaman.ai/agent/api/skills/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unpublish" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "message": "Skill unpublished from marketplace",
  "skillId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "SQL Query Best Practices",
  "type": "skill",
  "clientId": 42,
  "skill_manifest": {
    "content": "When writing SQL queries..."
  }
}

curl -X POST "http://kaman.ai/agent/api/skills/b2c3d4e5-f6a7-8901-bcde-f12345678901/install" \
  -H "Authorization: Bearer kam_your_api_key"

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "client_id": "42",
  "name": "SQL Query Best Practices",
  "slug": "sql-query-best-practices",
  "content": "When writing SQL queries...",
  "source_type": "marketplace",
  "is_marketplace": true,
  "status": "active",
  "created_at": "2026-02-17T10:00:00.000Z"
}

curl -X POST "http://kaman.ai/agent/api/skills/marketplace/search" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database optimization techniques",
    "limit": 5
  }'

[
  {
    "skillId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "SQL Query Best Practices",
    "description": "Guidelines for writing efficient and safe SQL queries",
    "domains": ["engineering", "data"],
    "trigger_keywords": ["sql", "query", "database"],
    "content_tokens": 256,
    "author": "Jane Doe",
    "sourceClientId": "99",
    "pluginId": null,
    "similarity": 0.82
  }
]

{
  "error": "Error message describing what went wrong"
}

const API_KEY = process.env.KAMAN_API_KEY;
const BASE_URL = 'http://kaman.ai';

// List skills with pagination
async function listSkills(limit = 50, offset = 0) {
  const response = await fetch(
    `${BASE_URL}/agent/api/skills?limit=${limit}&offset=${offset}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json(); // { skills: [...], totalCount: number }
}

// Semantic search
async function searchSkills(query: string, limit = 10) {
  const response = await fetch(`${BASE_URL}/agent/api/skills/search`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, limit })
  });
  return response.json();
}

// Create a skill
async function createSkill(name: string, content: string) {
  const response = await fetch(`${BASE_URL}/agent/api/skills`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name,
      content,
      domains: ['general'],
      trigger_keywords: ['example']
    })
  });
  return response.json();
}

// Publish to marketplace
async function publishSkill(skillId: string) {
  const response = await fetch(
    `${BASE_URL}/agent/api/skills/${skillId}/publish`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}

// Browse and install from marketplace
async function browseAndInstall(query: string) {
  const results = await fetch(
    `${BASE_URL}/agent/api/skills/marketplace/search`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, limit: 5 })
    }
  ).then(r => r.json());

  if (results.length > 0) {
    const installed = await fetch(
      `${BASE_URL}/agent/api/skills/${results[0].skillId}/install`,
      {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    ).then(r => r.json());
    return installed;
  }
}

import requests
import os

class KamanSkills:
    def __init__(self, base_url: str):
        self.base_url = f'{base_url}/agent/api/skills'
        self.headers = {
            'Authorization': f'Bearer {os.getenv("KAMAN_API_KEY")}',
            'Content-Type': 'application/json'
        }

    def list(self, limit=50, offset=0, status=None):
        """List skills with optional filters."""
        params = {'limit': limit, 'offset': offset}
        if status:
            params['status'] = status
        resp = requests.get(self.base_url, params=params, headers=self.headers)
        return resp.json()

    def search(self, query: str, limit=10, domains=None):
        """Semantic search for skills."""
        body = {'query': query, 'limit': limit}
        if domains:
            body['domains'] = domains
        resp = requests.post(f'{self.base_url}/search', json=body, headers=self.headers)
        return resp.json()

    def get(self, skill_id: str):
        """Get a skill by ID."""
        resp = requests.get(f'{self.base_url}/{skill_id}', headers=self.headers)
        return resp.json()

    def create(self, name: str, content: str, **kwargs):
        """Create a new skill."""
        body = {'name': name, 'content': content, **kwargs}
        resp = requests.post(self.base_url, json=body, headers=self.headers)
        return resp.json()

    def update(self, skill_id: str, **kwargs):
        """Update an existing skill."""
        resp = requests.put(f'{self.base_url}/{skill_id}', json=kwargs, headers=self.headers)
        return resp.json()

    def delete(self, skill_id: str):
        """Soft-delete a skill (sets status to deprecated)."""
        resp = requests.delete(f'{self.base_url}/{skill_id}', headers=self.headers)
        return resp.json()

    def publish(self, skill_id: str):
        """Publish a skill to the marketplace."""
        resp = requests.post(f'{self.base_url}/{skill_id}/publish', json={}, headers=self.headers)
        return resp.json()

    def unpublish(self, skill_id: str):
        """Unpublish a skill from the marketplace."""
        resp = requests.post(f'{self.base_url}/{skill_id}/unpublish', json={}, headers=self.headers)
        return resp.json()

    def search_marketplace(self, query: str, limit=10):
        """Search for installable marketplace skills."""
        body = {'query': query, 'limit': limit}
        resp = requests.post(f'{self.base_url}/marketplace/search', json=body, headers=self.headers)
        return resp.json()

    def install(self, skill_id: str):
        """Install a marketplace skill."""
        resp = requests.post(f'{self.base_url}/{skill_id}/install', json={}, headers=self.headers)
        return resp.json()

# Example usage
client = KamanSkills('http://kaman.ai')

# Create and publish a skill
skill = client.create(
    name='API Error Handling',
    content='When handling API errors:\n1. Always check HTTP status codes\n2. Parse error response bodies\n3. Implement exponential backoff for retries',
    domains=['engineering'],
    trigger_keywords=['api', 'error', 'retry']
)
client.publish(skill['id'])

# Search and install from marketplace
marketplace_skills = client.search_marketplace('error handling patterns')
for s in marketplace_skills:
    print(f"{s['name']} (similarity: {s['similarity']:.2f})")
if marketplace_skills:
    installed = client.install(marketplace_skills[0]['skillId'])