Browse and install

Browsing

Skills live at /skills and are searchable by free-text query. Listings sort by popular (downloads + ratings), recent, or highest rated. Each card carries:

• The skill @name and its kebab-case slug.
• Its @namespace — a JS identifier that determines the install location: window.xgoose.skills[<namespace>].
• The first line of the @description (a single sentence is best).
• Download count and a star average from reviews.

Click a card to land on /skill/?slug=<slug> — the detail page — for the full @description README, the canonical source, per-function summaries, the version history, and reviews.

The install flow

Every detail page has an Install in xgoose button. It is just a normal anchor that points at the canonical source URL:

https://api.xgoose.org/skills/<slug>.xgs.js

The xgoose extension registers a content script on *.xgs.js URLs. When you click the button:

1. The browser navigates to the source URL.
2. The extension's install-banner content script intercepts the navigation and redirects the tab to its own bundled install.html.
3. The install page parses the // ==XGooseSkill== header and lists every function the skill exposes (name, signature, summary, and which one is the primary? entry point).
4. You confirm. The extension calls saveUserSkill with the parsed header + bundled IIFE; the skill becomes available under window.xgoose.skills.<namespace> and is added to the agent's tool list whenever the page matches.

We use .xgs.js instead of .user.js on purpose, so a Tampermonkey install doesn't hijack the navigation before xgoose can. Browsers without the extension installed just see the raw script text — that's the expected fallback, and you can save the file by hand from there.

What the install banner shows

• The parsed header fields: @name, @namespace, @version, @author, @match / @include, optional @detect.
• The Markdown body from @description (rendered).
• The function table: every defineSkill().functions entry with its summary and Zod-derived JSON schema, generated by calling __describe__() on the bundle in the publisher's browser at publish time.

Treat the function table as the source of truth before you click confirm — skills run with the same privileges as the page they target.

Versioning and re-installs

Each skill carries a strict semver @version. When the publisher pushes a new build, the registry:

• Stores a new version row alongside the previous ones — history is never overwritten.
• Updates the latest_version_id on the parent skill so the canonical .xgs.js URL always points at the most recent build.
• If the publisher forgets to bump @version, the patch component is auto-bumped (same-owner only; cross-owner duplicate slug stays a 403). The response carries both submitted_version and version.

On re-install the extension compares versions and either prompts you to accept the upgrade or proceeds silently if you opted into auto-updates for that slug. Source for every historical version stays downloadable from the detail page.

Ratings and reviews

Once you've installed a skill, the detail page unlocks a Leave a review form: 1–5 stars plus an optional short comment. Reviews are public and tied to your account; you can edit your own. Skill authors can't delete reviews on their own listings — only the registry admin can, and only for clear spam.

Ownership and removal

• Slug ownership is locked to the first publisher.
• The owner can publish new versions at any time.
• Hard-deletes happen only via admin moderation (e.g. takedown for malicious code). If a skill you own no longer makes sense to host, publish a final version with a tombstone @description and stop updating — existing installs keep working, new users see the notice.