skillplus 0.1.2

Official Python SDK for SkillPlus

SkillPlus Python SDK

Official Python SDK for the hosted SkillPlus API.

SkillPlus provides security intelligence for AI skills and agent-facing software, helping developers, teams, and platforms scan, understand, and trust AI skills before installation, approval, or integration.

Install

pip install skillplus

Requires Python 3.10+.

Quick start

One call that always ends with a completed report — scanning first if the skill has never been seen:

from skillplus import SkillPlus

client = SkillPlus(api_key="skp_...")

report = client.wait_for_report("https://www.skills.sh/vercel-labs/skills/find-skills")
# GitHub repositories work the same way: "https://github.com/owner/repo"

print(report.verdict)  # "safe" | "medium" | "high" | "unknown" — UI labels: Safe / Caution / High Risk / Unrated
print(report.summary.total_issues)
if report.supply_chain:
    print(report.supply_chain.blacklist_hits)  # poisoned-dependency hits

Prefer verdict over the legacy rating field — it folds historical values onto the current three-tier scale.

Lower-level: check without waiting

query returns immediately with the current state (found / queued / running / not_found / failed) and never blocks:

result = client.query("https://www.skills.sh/vercel-labs/skills/find-skills")

if result.status == "found" and result.report:
    print(result.report.verdict)

Advanced options

For repositories containing many skills, or to queue a scan automatically when no report exists yet:

result = client.query(
    "https://github.com/owner/repo",       # multi-skill repos are usually on GitHub
    skill_path="skills/example",           # pick one skill in the repo
    scan_if_missing=True,                  # queue a scan if no report exists
)

Client options:

client = SkillPlus(
    api_key="skp_...",
    base_url="https://skillplus.xyz",  # staging / self-hosted override
    timeout=30.0,                      # per-request timeout (seconds)
    max_retries=2,                     # retries on 429/502/503, honoring Retry-After
)

Context manager

from skillplus import SkillPlus

with SkillPlus(api_key="skp_...") as client:
    result = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
    print(result.status)

Methods

Method	Use case
query(...)	Check whether SkillPlus already has a report for a skill.
scan(...)	Request a scan when a report is missing or when a fresh check is needed.
wait_for_report(...)	Query-and-wait: scans if missing, polls, and returns the completed report.
get_report(scan_id)	Retrieve structured report data: verdict, findings, AI audit, supply-chain snapshot.
get_badge(scan_id)	Fetch the badge SVG for embedding.
get_badge_url(scan_id)	Generate a badge URL for READMEs, marketplaces, or internal portals.

Error handling

from skillplus import SkillPlus, SkillPlusError

client = SkillPlus(api_key="skp_...")

try:
    result = client.query("https://www.skills.sh/vercel-labs/skills/find-skills")
except SkillPlusError as error:
    print(error.status_code)
    print(error.message)

Development

uv sync --extra dev
uv run pytest
uv build