Skills API

API endpoints for searching, retrieving, and managing skills.

Queries

skills.get

Get a skill by name.

const skill = await client.query(api.skills.get, {
  name: "typescript-strict-mode"
});

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Skill name

Response:

{
  _id: Id<"skills">,
  name: string,
  version: string,
  category: string,
  description: string,
  prompt: string,
  platforms: string[],
  use_cases: string[],
  tags: string[],
  confidence: number,
  execution_count: number,
  success_rate: number,
  agent_count: number,
  author: string,
  created_at: number,
  updated_at: number
}

skills.search

Search skills by query.

const results = await client.query(api.skills.search, {
  query: "typescript configuration",
  category: "coding",
  minConfidence: 0.8,
  platforms: ["claude-code"],
  limit: 10
});

Parameters:

Name	Type	Required	Description
`query`	string	Yes	Search query
`category`	string	No	Filter by category
`minConfidence`	number	No	Minimum confidence (0-1)
`platforms`	string[]	No	Filter by platforms
`limit`	number	No	Max results (default: 10)
`offset`	number	No	Pagination offset

Response:

{
  skills: Skill[],
  total: number,
  hasMore: boolean
}

skills.list

List all skills with optional filters.

const skills = await client.query(api.skills.list, {
  category: "coding",
  sortBy: "confidence",
  limit: 20
});

Parameters:

Name	Type	Required	Description
`category`	string	No	Filter by category
`sortBy`	string	No	Sort field (confidence, executions, created)
`sortOrder`	string	No	asc or desc
`limit`	number	No	Max results
`offset`	number	No	Pagination offset

skills.listAdvanced

Advanced listing with multiple filters.

const skills = await client.query(api.skills.listAdvanced, {
  categories: ["coding", "workflow"],
  platforms: ["claude-code", "cursor"],
  minConfidence: 0.75,
  hasActiveSession: true,
  sortBy: "trending",
  limit: 20
});

skills.getCategories

Get all available categories with counts.

const categories = await client.query(api.skills.getCategories);

Response:

[
  { name: "coding", count: 15234 },
  { name: "workflow", count: 4567 },
  { name: "security", count: 2341 }
]

skills.getLineage

Get skill fork/evolution history.

const lineage = await client.query(api.skills.getLineage, {
  name: "typescript-strict-mode"
});

Response:

{
  skill: Skill,
  parent: Skill | null,
  children: Skill[],
  evolutions: Evolution[],
  totalDescendants: number
}

skills.trendingEvolutions

Get skills with recent evolutions.

const trending = await client.query(api.skills.trendingEvolutions, {
  period: "week",
  limit: 10
});

skills.withActiveSessions

Get skills with active collaborative sessions.

const active = await client.query(api.skills.withActiveSessions, {
  limit: 10
});

Mutations

skills.create

Create a new skill.

const skillId = await client.mutation(api.skills.create, {
  name: "my-new-skill",
  version: "0.1.0",
  category: "coding",
  description: "My custom skill",
  prompt: "Skill instructions...",
  platforms: ["claude-code", "cursor"],
  use_cases: ["Use case 1", "Use case 2"],
  tags: ["typescript", "config"]
});

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Unique skill name
`version`	string	Yes	Semver version
`category`	string	Yes	Skill category
`description`	string	Yes	Brief description
`prompt`	string	Yes	Skill prompt
`platforms`	string[]	No	Supported platforms
`use_cases`	string[]	No	Use cases
`tags`	string[]	No	Searchable tags

skills.update

Update an existing skill.

await client.mutation(api.skills.update, {
  name: "my-skill",
  version: "0.2.0",
  prompt: "Updated instructions..."
});

skills.fork

Fork an existing skill.

const forkId = await client.mutation(api.skills.fork, {
  sourceName: "typescript-strict-mode",
  newName: "my-typescript-config",
  changes: {
    description: "My customized version"
  }
});

skills.delete

Delete a skill (author only).

await client.mutation(api.skills.delete, {
  name: "my-skill"
});

Real-time Subscriptions

client.subscribe(api.skills.get, { name: "typescript-strict-mode" }, (skill) => {
  console.log("Skill updated:", skill);
  console.log("New confidence:", skill.confidence);
});

client.subscribe(
  api.skills.search,
  { query: "typescript", limit: 5 },
  (results) => {
    console.log("Results updated:", results.skills.length);
  }
);

Examples

Search and Filter

// Search with multiple filters
const results = await client.query(api.skills.search, {
  query: "react hooks",
  category: "coding",
  platforms: ["claude-code"],
  minConfidence: 0.85,
  limit: 5
});

console.log(`Found ${results.total} skills`);
for (const skill of results.skills) {
  console.log(`${skill.name} - ${skill.confidence}%`);
}

Get Full Skill Details

const skill = await client.query(api.skills.get, {
  name: "typescript-strict-mode"
});

console.log(`
Skill: ${skill.name} v${skill.version}
Confidence: ${skill.confidence}%
Executions: ${skill.execution_count}
Success Rate: ${skill.success_rate}%

Prompt:
${skill.prompt}
`);

Fork and Customize

// Fork a skill
const forkId = await client.mutation(api.skills.fork, {
  sourceName: "typescript-strict-mode",
  newName: "typescript-strict-monorepo",
  changes: {
    description: "Strict TypeScript for monorepos",
    tags: [...originalTags, "monorepo", "turborepo"]
  }
});

// Update the fork
await client.mutation(api.skills.update, {
  name: "typescript-strict-monorepo",
  prompt: customizedPrompt
});