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

```typescript { .api }
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:

```typescript
client.beta.skills.*
client.beta.skills.versions.*
```

## Types

```typescript { .api }
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

```typescript { .api }
client.beta.skills.create(
  params: SkillCreateParams
): APIPromise<SkillCreateResponse>;

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

**Example:**

```typescript
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

```typescript
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

```typescript { .api }
client.beta.skills.retrieve(
  skillID: string,
  params?: SkillRetrieveParams
): APIPromise<SkillRetrieveResponse>;

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

**Example:**

```typescript
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

```typescript { .api }
client.beta.skills.list(
  params?: SkillListParams
): SkillListResponsesPageCursor;

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

**Example:**

```typescript
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

```typescript { .api }
client.beta.skills.delete(
  skillID: string,
  params?: SkillDeleteParams
): APIPromise<SkillDeleteResponse>;

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

**Example:**

```typescript
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

```typescript { .api }
client.beta.skills.versions.create(
  skillID: string,
  params: VersionCreateParams
): APIPromise<VersionCreateResponse>;

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

**Example:**

```typescript
// 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

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

**Example:**

```typescript
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

```typescript { .api }
client.beta.skills.versions.list(
  skillID: string,
  params?: VersionListParams
): VersionListResponsesPageCursor;
```

**Example:**

```typescript
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

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

**Example:**

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

## Complete Workflow

```typescript
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

```typescript
// ✅ 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

```typescript
// ✅ 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

```typescript
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](./messages.md) - Using skills in messages
- [Tools](./tools.md) - Tool use and skills
- [Beta Features](./beta-features.md) - Other beta capabilities