Metadata-Version: 2.4
Name: openapi-to-agent-skills
Version: 0.3.2
Summary: Convert OpenAPI specifications to Agent Skills format
Project-URL: Homepage, https://github.com/xuyong/openapi-to-agent-skills
Project-URL: Repository, https://github.com/xuyong/openapi-to-agent-skills
Author: Xu Yong
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: regex>=2024.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# openapi-to-agent-skills

Convert OpenAPI specifications to Agent Skills format — structured markdown documentation optimized for AI agents.

## Installation

```bash
pip install openapi-to-agent-skills
```

## Usage

```bash
openapi-to-agent-skills <path-or-url-to-openapi-spec> [OPTIONS]
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `-o, --output` | Output directory | `./output` |
| `-n, --name` | Skill name (derived from API title if omitted) | |
| `--include-tags` | Only include these tags (comma-separated) | |
| `--exclude-tags` | Exclude these tags (comma-separated) | |
| `--exclude-deprecated` | Exclude deprecated operations | `False` |
| `-t, --templates` | Custom templates directory | |
| `-a, --assets` | Static assets directory overlaid onto output | |
| `--exclude-paths` | Exclude paths matching prefixes (comma-separated) | |
| `-g, --group-by` | Grouping strategy: `tags`, `path`, `auto` | `auto` |
| `--case-strategy` | `lowercase` for case-insensitive filesystem safety | |
| `-f, --force` | Overwrite existing output directory | `False` |
| `-q, --quiet` | Suppress output except errors | `False` |

### Examples

```bash
# From a local file
openapi-to-agent-skills api.yaml -o ./skills

# From a URL
openapi-to-agent-skills https://petstore3.swagger.io/api/v3/openapi.json -o ./skills

# Filter by tags
openapi-to-agent-skills api.yaml --include-tags users,orders

# Case-safe output for Windows/macOS
openapi-to-agent-skills api.yaml --case-strategy lowercase
```

## Output Structure

```
<skill-name>/
├── SKILL.md                          # Entry point with YAML frontmatter
└── references/
    ├── authentication.md             # Auth schemes (if any)
    ├── resources/
    │   └── <tag>.md                  # One per resource group
    ├── operations/
    │   └── <operationId>.md          # One per operation
    └── schemas/
        └── <prefix>/
            ├── _index.md
            └── <SchemaName>.md       # One per schema
```

## Programmatic Usage

```python
from openapi_to_skills import convert_openapi_to_skill
from openapi_to_skills.types import ConvertOptions

import yaml

with open("api.yaml") as f:
    spec = yaml.safe_load(f)

convert_openapi_to_skill(spec, ConvertOptions(output_dir="./output"))
```

## License

MIT
