@secureskill/cli

Scan agent skills for security threats from the command line.

npm install -g @secureskill/cli

Quick start

# Fast cached lookup (~50ms, free)
secureskill ssp-check publisher/skill

# Full fresh scan (~30s, LLM-backed)
secureskill scan https://github.com/owner/repo

# Local directory scan (zips and uploads)
secureskill scan ./my-skill/

# JSON output for CI pipelines
secureskill scan ./my-skill/ --json --fail-on caution

Commands

| Command | What it does | When to use | |---|---|---| | scan <target> | Run a full security analysis on a fresh skill (~30s) | Full report needed; no cached result; you want the latest | | ssp-check <target> | Read a cached verification record from a .well-known/skill-security/ endpoint (~50ms) | Pre-install gate in CI; fast verdict lookup; repeated checks | | login [--api-key] | Authenticate via browser OAuth or paste an API key | Higher rate limits; scan history saved to your account | | whoami | Show current authentication status | Confirm which auth mode is active |

Run secureskill <command> --help for examples and full options.

scan vs ssp-check

These do different things at very different costs:

• scan runs SecureSkill's full security analysis against the skill right now — multiple deterministic detection layers combined with AI-based behavioral reasoning. Takes ~30 seconds and produces a complete report (findings, permissions, layer details, corroboration).
• ssp-check reads a pre-computed verification record from a .well-known/skill-security/{publisher}/{skill}.json endpoint. Returns in ~50ms. The verdict is whatever the most recent scan of that skill produced — could be minutes or weeks old depending on archive freshness.

In CI: prefer ssp-check for the install-gate check, fall back to scan only when no record exists.

Supported sources

URLs from these marketplaces resolve automatically:

• clawhub.ai
• skills.sh
• agentskill.sh
• skillsmp.com
• skillsdirectory.com
• lobehub.com
• github.com (any public repo or tree/<branch>/<path>)

Plus direct GitHub URLs and local directory uploads.

Authentication

Three modes, in priority order:

1. SECURESKILL_API_KEY env var — for CI/CD pipelines:

   export SECURESKILL_API_KEY=sk-your-key-here
   secureskill scan ./my-skill

2. Stored API key — set once via secureskill login --api-key, used until cleared
3. OAuth refresh token — set via secureskill login (opens browser)

Without any of these, scans run anonymously and are rate-limited to 20 scans/hour per IP.

Generate API keys at https://secureskill.ai/developers.

Exit codes

| Code | Meaning | |---|---| | 0 | SAFE (or below the --fail-on threshold) | | 1 | CAUTION or BLOCK (depending on --fail-on) | | 2 | Error (network, auth, server, malformed input) |

--fail-on accepts block (default), caution, or any.

CI/CD example (GitHub Actions)

- name: Pre-install verdict check
  run: npx @secureskill/cli ssp-check ${{ inputs.skill_id }} --fail-on caution
  env:
    SECURESKILL_API_KEY: ${{ secrets.SECURESKILL_API_KEY }}

- name: Full scan if no cached record
  if: failure()
  run: npx @secureskill/cli scan ./skills --json --fail-on caution
  env:
    SECURESKILL_API_KEY: ${{ secrets.SECURESKILL_API_KEY }}

Configuration

| Env var | Default | Purpose | |---|---|---| | SECURESKILL_API_KEY | (none) | Authenticated requests; takes priority over stored credentials | | SECURESKILL_API_URL | https://secureskill.ai | Override the API base URL (testing, self-hosted) |

Stored credentials live at ~/.secureskill/credentials.json (mode 0600).

More

• Full developer docs, HTTP API reference, rate limits, and pricing tiers: https://secureskill.ai/developers