codeflash-internal/.tessl/tiles/tessl/npm-anthropic-ai--sdk/docs/skills.md

Skills API (Beta)

The Skills API allows you to create and manage custom skills that extend Claude's capabilities with reusable, versioned components.

Overview

Skills enable:

• Define reusable capabilities for Claude
• Version management for skills
• Organized skill libraries
• Consistent behavior across conversations

Beta Feature: Requires betas: ['skills-2025-10-02']

API Reference

class Skills extends APIResource {
  create(params: SkillCreateParams): APIPromise<SkillCreateResponse>;
  retrieve(skillID: string, params?: SkillRetrieveParams): APIPromise<SkillRetrieveResponse>;
  list(params?: SkillListParams): SkillListResponsesPageCursor;
  delete(skillID: string, params?: SkillDeleteParams): APIPromise<SkillDeleteResponse>;

  // Sub-resource
  versions: Versions;
}

class Versions extends APIResource {
  create(skillID: string, params: VersionCreateParams): APIPromise<VersionCreateResponse>;
  retrieve(skillID: string, versionID: string, params?: VersionRetrieveParams): APIPromise<VersionRetrieveResponse>;
  list(skillID: string, params?: VersionListParams): VersionListResponsesPageCursor;
  delete(skillID: string, versionID: string, params?: VersionDeleteParams): APIPromise<VersionDeleteResponse>;
}

Access via:

client.beta.skills.*
client.beta.skills.versions.*

Types

interface SkillCreateResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
}

interface SkillRetrieveResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
  versions: VersionListResponse[];
}

interface SkillListResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
}

interface SkillDeleteResponse {
  id: string;
  type: 'skill';
  deleted: boolean;
}

interface VersionCreateResponse {
  id: string;
  skill_id: string;
  version: string;
  created_at: string;
}

interface VersionRetrieveResponse {
  id: string;
  skill_id: string;
  version: string;
  definition: any;  // Skill definition
  created_at: string;
}

Creating Skills

client.beta.skills.create(
  params: SkillCreateParams
): APIPromise<SkillCreateResponse>;

interface SkillCreateParams {
  name: string;
  description: string;
  definition: any;  // Skill implementation
  betas: ['skills-2025-10-02'];
}

Example:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const skill = await client.beta.skills.create({
  name: 'data_analyzer',
  description: 'Analyze structured data and provide insights',
  definition: {
    // Skill implementation details
    type: 'analysis',
    capabilities: ['statistics', 'visualization', 'trend_detection'],
  },
  betas: ['skills-2025-10-02'],
});

console.log('Skill ID:', skill.id);
console.log('Name:', skill.name);

Using Skills in Messages

const message = await client.beta.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 2048,
  betas: ['skills-2025-10-02'],
  skills: [
    {
      type: 'skill',
      skill_id: skill.id,
    },
  ],
  messages: [
    {
      role: 'user',
      content: 'Analyze this dataset and provide insights.',
    },
  ],
});

Retrieving Skills

client.beta.skills.retrieve(
  skillID: string,
  params?: SkillRetrieveParams
): APIPromise<SkillRetrieveResponse>;

interface SkillRetrieveParams {
  betas: ['skills-2025-10-02'];
}

Example:

const skill = await client.beta.skills.retrieve('skill_abc123', {
  betas: ['skills-2025-10-02'],
});

console.log('Skill:', skill.name);
console.log('Description:', skill.description);
console.log('Versions:', skill.versions.length);

Listing Skills

client.beta.skills.list(
  params?: SkillListParams
): SkillListResponsesPageCursor;

interface SkillListParams {
  limit?: number;
  next_page?: string;
  betas: ['skills-2025-10-02'];
}

Example:

const skills = await client.beta.skills.list({
  limit: 20,
  betas: ['skills-2025-10-02'],
});

for (const skill of skills.data) {
  console.log(`${skill.name}: ${skill.description}`);
}

// Auto-pagination
for await (const skill of client.beta.skills.list({ betas: ['skills-2025-10-02'] })) {
  console.log(skill.id);
}

Deleting Skills

client.beta.skills.delete(
  skillID: string,
  params?: SkillDeleteParams
): APIPromise<SkillDeleteResponse>;

interface SkillDeleteParams {
  betas: ['skills-2025-10-02'];
}

Example:

const deleted = await client.beta.skills.delete('skill_abc123', {
  betas: ['skills-2025-10-02'],
});

console.log('Deleted:', deleted.deleted); // true

Version Management

Skills support versioning for controlled updates:

Creating Versions

client.beta.skills.versions.create(
  skillID: string,
  params: VersionCreateParams
): APIPromise<VersionCreateResponse>;

interface VersionCreateParams {
  version: string;
  definition: any;
  betas: ['skills-2025-10-02'];
}

Example:

// Create new version
const version = await client.beta.skills.versions.create('skill_abc123', {
  version: '2.0.0',
  definition: {
    // Updated skill definition
    type: 'analysis',
    capabilities: ['statistics', 'visualization', 'trend_detection', 'forecasting'],
  },
  betas: ['skills-2025-10-02'],
});

console.log('Version created:', version.version);

Retrieving Versions

client.beta.skills.versions.retrieve(
  skillID: string,
  versionID: string,
  params?: VersionRetrieveParams
): APIPromise<VersionRetrieveResponse>;

Example:

const version = await client.beta.skills.versions.retrieve(
  'skill_abc123',
  '2.0.0',
  { betas: ['skills-2025-10-02'] }
);

console.log('Version:', version.version);
console.log('Definition:', version.definition);

Listing Versions

client.beta.skills.versions.list(
  skillID: string,
  params?: VersionListParams
): VersionListResponsesPageCursor;

Example:

const versions = await client.beta.skills.versions.list('skill_abc123', {
  betas: ['skills-2025-10-02'],
});

for (const version of versions.data) {
  console.log(`Version ${version.version} - ${version.created_at}`);
}

Deleting Versions

client.beta.skills.versions.delete(
  skillID: string,
  versionID: string,
  params?: VersionDeleteParams
): APIPromise<VersionDeleteResponse>;

Example:

await client.beta.skills.versions.delete(
  'skill_abc123',
  '1.0.0',
  { betas: ['skills-2025-10-02'] }
);

Complete Workflow

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

// 1. Create skill
const skill = await client.beta.skills.create({
  name: 'sentiment_analyzer',
  description: 'Analyze sentiment in text',
  definition: {
    type: 'text_analysis',
    models: ['sentiment'],
  },
  betas: ['skills-2025-10-02'],
});

// 2. Use skill
const message = await client.beta.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  betas: ['skills-2025-10-02'],
  skills: [
    {
      type: 'skill',
      skill_id: skill.id,
    },
  ],
  messages: [
    {
      role: 'user',
      content: 'Analyze the sentiment of this review: "This product is amazing!"',
    },
  ],
});

console.log('Analysis:', message.content[0].text);

// 3. Create new version
const version = await client.beta.skills.versions.create(skill.id, {
  version: '1.1.0',
  definition: {
    type: 'text_analysis',
    models: ['sentiment', 'emotion'],  // Added emotion detection
  },
  betas: ['skills-2025-10-02'],
});

// 4. Use specific version
const message2 = await client.beta.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  betas: ['skills-2025-10-02'],
  skills: [
    {
      type: 'skill',
      skill_id: skill.id,
      version: '1.1.0',  // Specific version
    },
  ],
  messages: [
    {
      role: 'user',
      content: 'Analyze sentiment and emotions.',
    },
  ],
});

// 5. Cleanup (optional)
// await client.beta.skills.delete(skill.id, { betas: ['skills-2025-10-02'] });

Best Practices

Skill Organization

// ✅ Good: Descriptive names and organization
const skills = {
  dataAnalysis: await client.beta.skills.create({
    name: 'data_analysis',
    description: 'Statistical analysis and visualization',
    definition: { /* ... */ },
    betas: ['skills-2025-10-02'],
  }),
  textSummarization: await client.beta.skills.create({
    name: 'text_summarization',
    description: 'Extract key points from documents',
    definition: { /* ... */ },
    betas: ['skills-2025-10-02'],
  }),
};

Version Control

// ✅ Good: Semantic versioning
await client.beta.skills.versions.create(skillId, {
  version: '2.1.0',  // major.minor.patch
  definition: { /* ... */ },
  betas: ['skills-2025-10-02'],
});

// ❌ Bad: Unclear versioning
await client.beta.skills.versions.create(skillId, {
  version: 'v2',
  definition: { /* ... */ },
  betas: ['skills-2025-10-02'],
});

Error Handling

try {
  const skill = await client.beta.skills.create({ /* ... */ });
} catch (error) {
  if (error instanceof Anthropic.BadRequestError) {
    console.error('Invalid skill definition');
  } else if (error instanceof Anthropic.ConflictError) {
    console.error('Skill with this name already exists');
  }
  throw error;
}

See Also

• Messages API - Using skills in messages
• Tools - Tool use and skills
• Beta Features - Other beta capabilities