SkillDock Python SDK and CLI

skilldock is an OpenAPI-driven Python client (and a simple CLI) for the SkillDock API.

It loads the OpenAPI spec at runtime and exposes:

• A Python SkilldockClient that can call any operationId
• A CLI that can list available operations and call them from your terminal

Package version: 2026.02.101309 (note: PyPI normalizes versions like 2026.02 to 2026.2 per PEP 440).

Install

pip install skilldock

Quickstart (CLI)

List operations from the OpenAPI spec:

skilldock ops

The first column is a python-friendly python_name you can use as client.ops.<python_name>(...).

Authenticate (browser login + polling):

skilldock auth login

This starts a CLI auth session on the API, prints an auth_url, opens it in your browser, then polls until it receives an app-issued access_token and saves it as the CLI token. Access tokens are short-lived; if you see auth errors later, run skilldock auth login again.

Create a long-lived personal API token (recommended for CI and to avoid short-lived JWT expiry):

# Prints the token (shown only once by the API) and saves it into the CLI config.
skilldock tokens create --save

# List your tokens
skilldock tokens list

Call an endpoint by operationId:

skilldock call SomeOperationId --param foo=bar --json '{"hello":"world"}'

Search skills:

skilldock skills search "docker"

Install a skill locally (default destination is ./skills, with recursive dependency resolution):

Public skills can be installed without auth. If a token is configured, the CLI sends it for skill discovery/install flows so private skills can be resolved when authorized.

# latest
skilldock install acme/my-skill

# exact version
skilldock i acme/my-skill --version 1.2.3

# custom local destination
skilldock install acme/my-skill --skills-dir /path/to/project/skills

Uninstall a direct skill and reconcile/remove no-longer-needed dependencies:

skilldock uninstall acme/my-skill

Verify a local skill folder (packages a zip and prints sha256/size):

skilldock skill verify .

Upload a new skill release:

skilldock skill upload --namespace myorg --slug my-skill --version 1.2.3 --path .

# Explicit private publish
skilldock skill upload --namespace myorg --slug my-skill --version 1.2.3 --path . --visibility private

This packages the folder into a zip and uploads it as multipart form field file. If your API supports release dependencies, you can pass them from CLI too:

# Repeatable string form:
skilldock skill upload --namespace myorg --slug my-skill --path . \
  --dependency "core/base-utils@^1.2.0" \
  --dependency "tools/lint@>=2.0.0 <3.0.0"

# JSON form (array or map), inline or from file:
skilldock skill upload --namespace myorg --slug my-skill --path . \
  --dependencies-json @dependencies.json

If you haven't created the namespace yet:

skilldock namespaces create myorg
skilldock namespaces list

Low-level request (method + path, bypassing operationId):

skilldock request GET /health

Quickstart (Python)

from skilldock import SkilldockClient

client = SkilldockClient(
    # Optional: override if needed
    openapi_url="https://api.skilldock.io/openapi.json",
    # base_url="https://api.skilldock.io",
    token=None,  # set after `skilldock auth login`
)

ops = client.operation_ids()
print("operations:", len(ops))

# Call by operationId (params are split into path/query/header based on OpenAPI metadata)
result = client.call_operation("SomeOperationId", params={"id": "123"})
print(result)

# Or call by a generated python-friendly name:
# (see `skilldock ops` output and use the `python_name`-like identifier)
# result = client.ops.someoperationid(id="123")

client.close()

Configuration

The CLI stores config (including token) in a local JSON file:

skilldock config path
skilldock config show

You can set config values:

skilldock config set --base-url https://api.skilldock.io --openapi-url https://api.skilldock.io/openapi.json
skilldock config set --token "YOUR_TOKEN"

Environment variables (override config):

• SKILLDOCK_OPENAPI_URL
• SKILLDOCK_BASE_URL
• SKILLDOCK_TOKEN
• SKILLDOCK_TIMEOUT_S

Authentication Notes (Google)

This SDK assumes the API accepts a token in an HTTP header (usually Authorization: Bearer <token>). The exact details are derived from the OpenAPI securitySchemes when present.

The SkillDock API can accept (depending on server configuration):

• Google ID token (JWT)
• App-issued access token (JWT, returned by the CLI OAuth flow)
• Personal API token (opaque string, created via skilldock tokens create)

skilldock auth login works like this:

1. Creates a CLI auth session via POST /auth/cli/sessions
2. Prints the returned auth_url and opens it in your browser
3. After you complete Google login, the backend approves the session
4. The CLI polls GET /auth/cli/sessions/{session_id} until it receives an app-issued access_token, then saves it as the configured API token

If you want to set a token manually:

skilldock auth set-token "PASTE_TOKEN_HERE"

To create a personal API token (recommended for longer-lived auth):

skilldock tokens create --save

Development

Run the small unit test suite:

python -m unittest discover -s tests