Generate SKILL.md files from your supypowers tools for seamless integration with Claude Code.

Claude Code Integration

Claude Code can discover and use your supypowers tools through the Agent Skills format. By generating SKILL.md files, you give Claude Code full knowledge of your tools -- their names, descriptions, input schemas, and how to invoke them.

How It Works

Your powers/ directory
  ├── weather.py
  ├── database.py
  └── deploy.py
        │
        v
  supypowers skills  (generates SKILL.md files)
        │
        v
  .claude/skills/
  ├── supypower-weather/SKILL.md
  ├── supypower-database/SKILL.md
  └── supypower-deploy/SKILL.md
        │
        v
  Claude Code reads SKILL.md files → knows how to call your tools

Generating Skills

Run the supypowers skills command from your project root:

supypowers skills

Output:

{
  "ok": true,
  "skills": 3,
  "functions": 7,
  "output_dir": ".claude/skills"
}

This creates one directory per script in .claude/skills/:

.claude/skills/
  supypower-weather/
    SKILL.md
  supypower-database/
    SKILL.md
  supypower-deploy/
    SKILL.md

Options

# Custom output directory
supypowers skills --output .claude/skills

# Print to stdout instead of writing files
supypowers skills --stdout

# Pass secrets if scripts need them to load
supypowers skills --secrets .env

The SKILL.md Format

Each generated SKILL.md file follows the Agent Skills format with YAML frontmatter:

---
name: supypower-weather
description: >-
  Run Weather functions via supypowers CLI. Available: get current weather
  for a city. Use when the user needs weather functionality.
---

# Weather

Execute tools: `supypowers run <script>:<function> '<json>'`

Output: `{"ok": true, "data": ...}` on success, `{"ok": false, "error": "..."}` on failure.

### weather:get_weather

Get the current weather for a city. Returns temperature and conditions.

```bash
supypowers run weather:get_weather '{"city": "..."}'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | yes | City name (e.g., 'San Francisco') |
| `units` | string | no | Temperature units: 'metric' or 'imperial' |

Frontmatter Fields

Field	Purpose
`name`	Unique skill identifier (prefixed with `supypower-`)
`description`	When Claude Code should use this skill. Includes available actions

How Claude Code Uses Skills

When Claude Code starts, it scans .claude/skills/ for SKILL.md files. For each skill:

The description field tells Claude when to use the skill
The function documentation tells Claude the exact command to run
The input table tells Claude what parameters are available
Claude executes the tool via supypowers run in the terminal

Example Interaction

User: What's the weather in Tokyo?

Claude Code:
  1. Reads .claude/skills/supypower-weather/SKILL.md
  2. Identifies weather:get_weather as the right function
  3. Runs: supypowers run weather:get_weather '{"city": "Tokyo"}'
  4. Parses the JSON output
  5. Responds: "The current temperature in Tokyo is 22°C with clear skies."

Full Walkthrough

1. Create a Tool

supypowers new stock_price

Edit powers/stock_price.py:

powers/stock_price.py

# /// script
# dependencies = ["pydantic", "httpx"]
# ///
"""Stock price lookup tool."""
import httpx
from typing import Optional
from pydantic import BaseModel, Field


class LookupInput(BaseModel):
    ticker: str = Field(..., description="Stock ticker symbol (e.g., 'AAPL')")


class LookupOutput(BaseModel):
    ok: bool
    ticker: Optional[str] = None
    price: Optional[float] = None
    error: Optional[str] = None


def lookup(input: LookupInput) -> LookupOutput:
    """Look up the current price of a stock by ticker symbol."""
    try:
        # Example API call
        resp = httpx.get(f"https://api.example.com/stocks/{input.ticker}")
        data = resp.json()
        return LookupOutput(ok=True, ticker=input.ticker, price=data["price"])
    except Exception as e:
        return LookupOutput(ok=False, error=str(e))

2. Test the Tool

supypowers test stock_price:lookup

3. Generate Skills

supypowers skills

4. Use in Claude Code

Open Claude Code in your project directory. It automatically discovers the skill:

User: What's the current price of AAPL?

Claude Code runs: supypowers run stock_price:lookup '{"ticker": "AAPL"}'
Claude Code responds: "Apple (AAPL) is currently trading at $187.50."

Keeping Skills Up to Date

Re-run supypowers skills whenever you:

Add a new tool to powers/
Change a tool's input schema or description
Remove a tool

The command automatically cleans up stale skill directories (any supypower-* directory for scripts that no longer exist).

Cloud Integration Skills

If you're using Supyagent Cloud integrations, the supyagent skills generate command creates skills for both local tools and cloud services:

supyagent skills generate

This generates skills for:

All local supypowers tools in powers/
All connected cloud integrations (Gmail, Slack, GitHub, etc.)

Tips

Commit .claude/skills/ to your repository so the whole team benefits
Write clear docstrings on your functions -- they become the skill descriptions
Use descriptive Field(description=...) on all input fields -- Claude reads these
Keep function names descriptive: get_weather is better than gw
The --stdout flag is useful for piping skill content to other tools

What's Next

Creating Tools -- Build tools for Claude Code to use
Codex -- Integration with OpenAI Codex
Execution Mode -- Automation pipelines

Claude Code

On this page