Creating Skills

Custom skills let you teach Claude your specific workflows, tools, and best practices.

When to Create a Skill

Create a skill when you have:

• A repeatable process Claude should follow
• Domain expertise to encode
• Specific tools or libraries to use
• Patterns that improve output quality

Skill File Structure

• Directory.claude/

  • Directoryskills/

    • Directorymy-skill/

      • SKILL.md
      • Directorytemplates/ (optional)

        • …
      • Directoryexamples/ (optional)

        • …

Creating Your First Skill

1. Create the directory

   mkdir -p .claude/skills/api-client

2. Create SKILL.md

   touch .claude/skills/api-client/SKILL.md

3. Write the skill

   See template below.

4. Test the skill

   > use the api-client skill to create a client for the GitHub API

SKILL.md Template

# Skill: [Skill Name]

## Overview
[One paragraph describing what this skill does]

## When to Use
[List of triggers that should activate this skill]
- User asks to "[trigger phrase]"
- User needs to "[task description]"

## Prerequisites
[Required tools, libraries, or setup]
- Python 3.10+
- requests library

## Process
[Step-by-step instructions Claude should follow]

1. [First step]
2. [Second step]
3. [Third step]

## Best Practices
[Quality guidelines and patterns to follow]
- [Practice 1]
- [Practice 2]

## Code Template
[Working code example Claude can adapt]

```python
# Example implementation

Common Mistakes

[Pitfalls to avoid]

• [Mistake 1]: [How to avoid]
• [Mistake 2]: [How to avoid]

Examples

Example 1: [Scenario]

Input: [What user might ask] Output: [What Claude should produce]

## Example: API Client Skill

```markdown
# Skill: Python API Client Generator

## Overview
Creates well-structured Python API clients with proper error
handling, retry logic, and type hints.

## When to Use
- User asks to "create an API client"
- User needs to "wrap an API"
- User wants to "integrate with [service] API"

## Prerequisites
- Python 3.10+
- requests
- pydantic (for models)

## Process

1. Analyze the API (docs or OpenAPI spec)
2. Identify endpoints and data models
3. Create base client class with:
   - Authentication handling
   - Request/response logging
   - Error handling
   - Retry logic
4. Generate endpoint methods
5. Create Pydantic models for requests/responses
6. Add type hints throughout
7. Write basic tests

## Best Practices

- Use httpx for async support
- Implement exponential backoff for retries
- Create custom exceptions for API errors
- Use environment variables for credentials
- Add request ID tracking for debugging

## Code Template

```python
import httpx
from pydantic import BaseModel
from typing import Optional
import os

class APIError(Exception):
    def __init__(self, status_code: int, message: str):
        self.status_code = status_code
        self.message = message
        super().__init__(f"{status_code}: {message}")

class BaseClient:
    def __init__(self, base_url: str, api_key: Optional[str] = None):
        self.base_url = base_url
        self.api_key = api_key or os.getenv("API_KEY")
        self.client = httpx.Client(
            base_url=base_url,
            headers={"Authorization": f"Bearer {self.api_key}"},
            timeout=30.0
        )

    def _request(self, method: str, path: str, **kwargs):
        response = self.client.request(method, path, **kwargs)
        if not response.is_success:
            raise APIError(response.status_code, response.text)
        return response.json()

Common Mistakes

• Hardcoding credentials: Always use environment variables
• No timeout: Set reasonable timeouts to prevent hanging
• Silent failures: Always raise or log errors
• Missing types: Use type hints for all public methods

Examples

Example 1: GitHub API Client

Input: “create an API client for GitHub’s repos endpoint”

Output:

• github_client.py with GitHubClient class
• models.py with Repository, User Pydantic models
• tests/test_github_client.py with basic tests

## Skill Discovery

Claude finds skills in:

1. `.claude/skills/` in your project
2. User skills directory
3. Built-in skills

<Aside type="tip">
Name your skill directory descriptively. Claude uses the directory name to match skills to tasks.
</Aside>

## Testing Your Skill

use the api-client skill to create a client for [some API]

Check if Claude followed the skill

did you follow the api-client skill guidelines?

## Sharing Skills

### With Your Team

Add skills to your repo:

```bash
git add .claude/skills/
git commit -m "Add custom API client skill"

Globally

Copy to your user skills directory:

cp -r .claude/skills/my-skill ~/.claude/skills/

Advanced: Skill with Templates

Include template files your skill can use:

• Directory.claude/skills/flask-app/

  • SKILL.md
  • Directorytemplates/

    • app.py.template
    • config.py.template
    • requirements.txt.template

Reference in SKILL.md:

## Templates
Use templates from `templates/` directory as starting points.
Customize based on user requirements.