Metadata-Version: 2.4
Name: aiskillstore
Version: 1.0.0
Summary: Python SDK for the Universal Skill Kit (USK) Skill Store API
License: MIT
Project-URL: Homepage, https://aiskillstore.io
Project-URL: Documentation, https://aiskillstore.io/guide
Project-URL: Repository, https://github.com/your-org/skillstore-sdk
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Skill Store SDK

Python client for the [Universal Skill Kit (USK)](https://aiskillstore.io) Skill Store API.

Zero external dependencies — uses Python stdlib only.

## Install

```bash
pip install aiskillstore
```

Or copy the `skillstore_sdk/` directory into your project.

## Quick Start

```python
from skillstore_sdk import SkillStore

store = SkillStore()  # defaults to https://aiskillstore.io

# Search for skills
results = store.search(capability="web_search", min_trust="community")
for skill in results:
    print(skill.name, skill.trust_level, skill.capabilities)

# Get full schema before installing
schema = store.schema(results[0].skill_id)
print(schema.call_example())      # {'query': 'Search query string'}
print(schema.permissions)         # {'network': True, 'filesystem': False, ...}
print(schema.interface)           # {'type': 'cli', 'call_pattern': 'stdin_stdout', ...}

# Download for your platform
path = store.download(results[0].skill_id, platform="OpenClaw", target_dir="./skills/")
print(f"Downloaded to {path}")

# One-liner: search + download
path = store.find_and_download("web_search", platform="ClaudeCode", target_dir="./skills/")
```

## Authentication

Read operations (search, schema, download) require no authentication.

Upload requires an API key obtained from your Skill Store account:

```python
store = SkillStore(api_key="sk_your_key_here")
# or via env var:
# export SKILLSTORE_API_KEY=sk_your_key_here

result = store.upload("./my-skill-1.0.0.skill")
print(result["vetting_report"]["status"])
```

## Configuration

| Parameter | Env var | Default |
|-----------|---------|---------|
| `base_url` | `SKILLSTORE_URL` | `https://aiskillstore.io` |
| `api_key` | `SKILLSTORE_API_KEY` | *(none)* |
| `timeout` | — | `30` seconds |

```python
store = SkillStore(
    base_url="https://aiskillstore.io",
    api_key="sk_...",
    timeout=60,
)
```

## API Reference

### `store.info()` → dict
Returns service metadata including USK spec version and supported platforms.

### `store.search(...)` → SearchResult
Search for skills by capability, keyword, platform, or trust level.

```python
results = store.search(
    capability="translation",   # semantic capability tag
    q="korean",                 # keyword search
    platform="OpenClaw",        # filter by platform
    usk_v3=True,                # only auto-convertible skills
    trust="verified",           # exact trust level
    min_trust="community",      # minimum trust level
    limit=10,                   # max results (default 20, max 50)
)
# SearchResult is iterable
for skill in results:
    print(skill)  # <Skill my-skill v1.0.0 | verified [USK v3] ⚡>
```

### `store.schema(skill_id)` → SkillSchema
Fetch the full USK schema for a skill. Use this to evaluate a skill before installing.

```python
s = store.schema("abc123")
s.call_example()           # minimal valid input dict
s.interface                # {'type': 'cli', 'entry_point': 'main.py', ...}
s.input_schema             # JSON Schema dict
s.output_schema            # JSON Schema dict
s.permissions              # {'network': bool, 'filesystem': bool, ...}
s.platform_compatibility   # ['OpenClaw', 'ClaudeCode', 'CustomAgent']
```

### `store.download(skill_id, platform, target_dir, filename)` → str
Download a skill package. Returns the absolute path to the saved file.

Supported platforms: `"OpenClaw"` | `"ClaudeCode"` | `"CustomAgent"` | `"original"`

### `store.upload(skill_file_path)` → dict
Upload a `.skill` package. Requires `api_key`.

Returns `{"status": ..., "skill_name": ..., "version_number": ..., "vetting_report": {...}}`.

### `store.find_and_download(capability, platform, target_dir, trust)` → str | None
Convenience: search by capability and download the top result. Returns `None` if no match.

## Trust Levels

| Level | Meaning |
|-------|---------|
| `verified` | Admin-approved, manually reviewed |
| `community` | Auto-scan passed, community-trusted |
| `sandbox` | Unchecked — use with caution |

## Supported Platforms

| Platform | Package Type |
|----------|-------------|
| `OpenClaw` | `openclaw_wrapper.py` + `openclaw_manifest.json` |
| `ClaudeCode` | Markdown slash command + `runner.py` |
| `CustomAgent` | HTTP adapter (`/invoke`) + `openapi.json` |
| `original` | Original uploaded package |

USK v3 skills with `can_auto_convert: true` are automatically available for all platforms.

## Agent Usage Pattern

Agents typically follow this discovery-evaluate-install flow:

```python
from skillstore_sdk import SkillStore

store = SkillStore(base_url="https://aiskillstore.io")

# 1. Discover
results = store.search(capability="web_search", min_trust="community", usk_v3=True)
if not results:
    raise RuntimeError("No web_search skill available")

# 2. Evaluate — check permissions before installing
top = results[0]
schema = store.schema(top.skill_id)
if schema.permissions.get("filesystem"):
    raise RuntimeError("Skill requests filesystem access — not allowed")

# 3. Install
path = store.download(top.skill_id, platform="OpenClaw", target_dir="./skills/")
print(f"Installed: {path}")
```
