Skill Sources¶

Point Soulacy at any URL (a skill directory like skills.sh, a Soulacy registry, or a git host) and it identifies what it is, shows you what it found, and adds it as an install source only after you consent.

Quick start¶

sy registry probe https://www.skills.sh/    # review only, changes nothing
sy registry add   https://www.skills.sh/    # review + consent + save to config.yaml
sy registry list                            # configured sources

After adding skills.sh, install directly by skills.sh id (owner/repo/skill):

sy skill install vercel-labs/skills/find-skills

Reviewing a URL: `sy registry probe`¶

Probing runs entirely client-side (no gateway needed) and never modifies your config. The report shows:

URL:    https://www.skills.sh/
Kind:   skillssh
Review: …
Audits: third-party security audits available; Soulacy's own introspection still runs on every install
Found:
  - …sample skills/repos discovered…
Suggested config entry: id=skills.sh type=skillssh base_url=https://www.skills.sh priority=50

Pass the CLI's global --json flag to get the raw probe report instead.

What detection recognises¶

Kind	Detected as	What it means
`skillssh`	skills.sh-compatible directory API	A skill directory; slugs are skills.sh ids `owner/repo/skill`
`http`	Soulacy package registry (`/v1/search` shape)	A registry serving versioned, checksummed packages
`git`	known git host	Addressed installs: `sy skill install github.com/owner/repo`
`unknown`	plain web page	Not a registry. The report lists any GitHub repos the page links, each installable directly as a git source.

When a source publishes partner security audits (skills.sh does), the probe report flags it, and those audits are surfaced again in the install consent prompt.

External audits never replace local checks

Third-party audits are extra signal, not a bypass. Soulacy's own safety introspection pipeline still runs on every install, regardless of source.

Adding a source: `sy registry add`¶

sy registry add https://www.skills.sh/

This probes, prints the same report, then asks:

Add source "skills.sh" (type skillssh, https://www.skills.sh) to config.yaml? [y/N]

Flags:

Flag	Effect
`--id <id>`	override the suggested source id
`--priority <n>`	resolution priority (lower runs first)
`--yes`, `-y`	skip the confirmation prompt

Saving goes through the gateway API when it is reachable (so the GUI sees the change immediately); when the gateway is down, the entry is appended directly to config.yaml. Duplicate ids are refused either way.

sy skill install picks up new sources immediately; GUI installs use the new source after a gateway restart.

End-to-end example: skills.sh¶

# 1. Review and add the source
sy registry add https://www.skills.sh/

# 2. Install a skill by its skills.sh id (owner/repo/skill)
sy skill install vercel-labs/skills/find-skills

The install resolves the id through skills.sh and fetches the skill's files (from the directory API when you have a token, otherwise from the skill's GitHub repository; see below). It then runs the local safety pipeline, shows any partner security audit next to Soulacy's own report at the consent prompt, and hot-loads the skill once you approve.

skills.sh authentication¶

Since October 2026 the skills.sh API (search, leaderboard and skill detail) answers HTTP 401 authentication_required unless the request carries a Vercel OIDC token (Authorization: Bearer <VERCEL_OIDC_TOKEN>, see skills.sh/docs/api). Those tokens are issued to apps deployed on Vercel. Only the audit endpoint (/api/v1/skills/audit/{id}) is still public.

Soulacy keeps skills.sh usable without a token:

Operation	Without a token	With a token
`sy skill install owner/repo/skill`	Shallow-clones `github.com/owner/repo` and installs the directory whose `SKILL.md` matches the skill (directory name or frontmatter `name`; a repo with a single `SKILL.md` installs that one)	Files come inline from the directory API
Search	Matches against the public catalog on the skills.sh homepage (popular skills only)	Full API search
Partner audits in the consent prompt	✓ (public endpoint)	✓
`sy registry probe https://www.skills.sh/`	Detected as `skillssh`, with samples from the public catalog and a note that the API is token-gated	Detected via the API
Well-known ids (`domain/skill`)	Not installable; the error explains why and what to do instead	✓

The git fallback installs the repository's default branch (HEAD). As with any git source the package is unsigned, so --allow-unverified is still required.

To use the API directly, provide a token in either of two ways:

# picked up automatically for skills.sh sources with no auth_headers
export VERCEL_OIDC_TOKEN=…   # e.g. from `vercel link && vercel env pull` (valid ~12h)

registries:
  - id: skills.sh
    type: skillssh
    base_url: https://www.skills.sh
    priority: 50
    auth_headers:
      Authorization: "Bearer <token>"   # sent verbatim; no env expansion

If a skill can't be reached either way, install it straight from its repository directory instead:

sy skill install https://github.com/vercel-labs/skills/tree/main/skills/find-skills

Adding sources from the GUI¶

On the Skills page:

Click ➕ Skill sources.
The modal lists your configured sources (id, type, URL, and a 🔑 marker when auth headers are configured).
Paste a URL and click 🔍 Review: the probe report renders inline: the detected kind, a review summary, sample skills/repos, and whether the source publishes third-party security audits.
If the URL is a recognisable registry, click ➕ Add "…" as a source.

The GUI uses the gateway endpoints GET/POST /api/v1/registries and POST /api/v1/registries/probe; all of them require config-level RBAC.

What gets written¶

Adding a source appends one entry to the registries: block in config.yaml:

registries:
  - id: skills.sh
    type: skillssh
    base_url: https://www.skills.sh
    priority: 50

Sources are queried in ascending priority order with fallback: the first registry that resolves a slug wins. For the full config grammar (auth headers, ed25519 signing keys, running your own registry) see Package Registries.

Adding a source is a trust decision

Anyone who controls a configured source can offer packages under any slug it serves. Keep priorities such that your most-trusted registries resolve first, pin signing_key on http registries you operate, and rely on the per-install security report: it runs no matter where a package came from.