---
name: {{ skill_name }}
description: "{{ description | replace('"', '\\"') }}"
---

# {{ skill_name }}

{{ description }}

## Authentication

{% if auth_type == "none" %}
No authentication required.

```python
app = {{ class_name }}()
```

Passing an `auth` argument is accepted but has no effect and will emit a warning.
{% elif auth_type == "bearer" %}
This MCP server uses **Bearer token** authentication. The API key is persisted
to `~/.mcp-skill/auth/` after first use, so subsequent runs can omit it.

```python
# First use — provide and persist the key
app = {{ class_name }}(auth="YOUR_API_KEY")

# Subsequent uses — loaded from disk automatically
app = {{ class_name }}()
```

The key is sent as `Authorization: Bearer <auth>` on every request.
{% elif auth_type == "header" %}
This MCP server uses a custom **`{{ auth_header }}`** header for authentication.
The API key is persisted to `~/.mcp-skill/auth/` after first use, so subsequent
runs can omit it.

```python
# First use — provide and persist the key
app = {{ class_name }}(auth="YOUR_API_KEY")

# Subsequent uses — loaded from disk automatically
app = {{ class_name }}()
```

The key is sent as `{{ auth_header }}: <auth>` on every request.
{% elif auth_type == "oauth" %}
This MCP server uses **OAuth** authentication.
The OAuth flow is handled automatically by the MCP client. Tokens are persisted
to `~/.mcp-skill/auth/` so subsequent runs reuse the same credentials without
re-authenticating.

```python
app = {{ class_name }}()  # uses default OAuth flow
```

To bring your own OAuth provider, pass it via the `auth` argument:

```python
app = {{ class_name }}(auth=my_oauth_provider)
```
{% endif %}

## Dependencies

This skill requires the following Python packages:

- `mcp-skill`

Install with uv:

```bash
uv pip install mcp-skill
```

Or with pip:

```bash
pip install mcp-skill
```

## How to Run

**Important:** Add `.agents/skills` to your Python path so imports resolve correctly:

```python
import sys
sys.path.insert(0, ".agents/skills")
from {{ module_name }}.app import {{ class_name }}
```

Or set the `PYTHONPATH` environment variable:

```bash
export PYTHONPATH=".agents/skills:$PYTHONPATH"
```

**Preferred: use `uv run`** (handles dependencies automatically):

```bash
PYTHONPATH=.agents/skills uv run --with mcp-skill python -c "
import asyncio
from {{ module_name }}.app import {{ class_name }}

async def main():
{% if auth_type in ('bearer', 'header') %}
    app = {{ class_name }}(auth='YOUR_API_KEY')
{% else %}
    app = {{ class_name }}()
{% endif %}
    result = await app.{{ tools[0].safe_method if tools else 'list_tools' }}({{ tools[0].example_args if tools else '' }})
    print(result)

asyncio.run(main())
"
```

**Alternative: use `python` directly** (install dependencies first):

```bash
pip install mcp-skill
PYTHONPATH=.agents/skills python -c "
import asyncio
from {{ module_name }}.app import {{ class_name }}

async def main():
{% if auth_type in ('bearer', 'header') %}
    app = {{ class_name }}(auth='YOUR_API_KEY')
{% else %}
    app = {{ class_name }}()
{% endif %}
    result = await app.{{ tools[0].safe_method if tools else 'list_tools' }}({{ tools[0].example_args if tools else '' }})
    print(result)

asyncio.run(main())
"
```

{% if tools %}
## Available Tools

{% for tool in tools %}
### {{ tool.name }}

{{ tool.description or "No description available." }}

{% if tool.params %}
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
{% for p in tool.params %}
| {{ p.name }} | `{{ p.type }}` | {{ "Yes" if p.required else "No" }} | {{ p.description }} |
{% endfor %}

{% endif %}
**Example:**
```python
result = await app.{{ tool.safe_method }}({{ tool.example_args }})
```

{% endfor %}
{% else %}
## Available Tools

No tools available.
{% endif %}
