[DOCS] Python SDK skills.create example creates empty skill with no parameters

Documentation Type

Missing code examples

Documentation Location

https://platform.claude.com/docs/en/api/python/beta/skills/create

Section/Topic

Example section

Current Documentation

import os
from anthropic import Anthropic

client = Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY"),  # This is the default and can be omitted
)
skill = client.beta.skills.create()
print(skill.id)

What's Wrong or Missing?

The example creates a skill with no parameters:

• No display_title
• No files

While parameters are technically optional, creating an empty skill serves no practical purpose for a developer reading the guide. The example doesn't demonstrate:

• How to give the skill a meaningful name
• How to upload the required SKILL.md file
• Any realistic workflow

The docs even state that skills "must include a SKILL.md file at the root" under the files parameter, but the example doesn't show this.

Suggested Improvement

Update the example to show a realistic skill creation:

Before:

skill = client.beta.skills.create()

After:

skill = client.beta.skills.create(
display_title="Code Review Assistant",
files=[
("SKILL.md", b"# Code Review\n\nReview code for best practices..."),
("guidelines.md", b"# Guidelines\n\n- Check for security issues..."),
],
)
print(f"Created skill: {skill.id}")

Or using file paths:

from pathlib import Path

skill = client.beta.skills.create(
display_title="Code Review Assistant",
files=[
Path("my-skill/SKILL.md"),
Path("my-skill/guidelines.md"),
],
)

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | SDK | Line | Context |
|------|-----|------|---------|
| https://platform.claude.com/docs/en/api/python/beta/skills/create | Python | 123 | Empty skills.create() |
| https://platform.claude.com/docs/en/api/python/beta/skills | Python | (same) | Rolled-up page |
| https://platform.claude.com/docs/en/api/python/beta | Python | (same) | Rolled-up page |
| https://platform.claude.com/docs/en/api/typescript/beta/skills/create | TypeScript | (same) | Empty example |
| https://platform.claude.com/docs/en/api/typescript/beta/skills | TypeScript | (same) | Rolled-up page |
| https://platform.claude.com/docs/en/api/typescript/beta | TypeScript | (same) | Rolled-up page |

Total scope: 6 files with empty skills.create() examples.

Pattern searched: skills\.create\(\)