v2.1.0

Upgrade notes

This release records every download and adds a download log for each skill, each project and the whole instance. Nothing that installs skills changes: install commands, keys, CLI sign-ins and the publish API work as before.

• Migration 0008_download_logs.sql adds the tables for download records and their daily totals. It leaves existing tables alone, and every skill keeps its download count. The log starts empty: downloads made before the upgrade are not in it.
• The Worker now has an hourly Cron Trigger, 17 * * * *. Workers Free allows 5 Cron Triggers per account, so if your account already uses all 5, the deploy fails until you free one.
• Every download now stores the IP address and User-Agent of the request, along with the account, the computer for a CLI sign-in and the country. If your instance has a privacy notice, update it.
• Records are kept for 90 days. To change that, add DOWNLOAD_LOG_RETENTION_DAYS as a Text variable in the Worker's Settings → Variables and Secrets; docs/deploy.md has the details. wrangler.jsonc now sets keep_vars, so later deploys keep variables you add in the dashboard.

To upgrade with Wrangler, pull and deploy. npm run deploy applies the migration first:

git pull
npm install
npm run deploy

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again, applies the migration and adds the Cron Trigger.

npm run verify:cli now starts wrangler dev with --test-scheduled and runs the hourly job itself before it checks download counts. Run npm run db:migrate:local first so your local database has the new tables.

Added

• A download log for each skill, each project and the whole instance.
  • A skill's log is at /p/<project>/s/<skill>/downloads. The download count on the skill's page links to it for whoever can manage the skill.
  • A project's log is at /p/<project>/downloads. Its admins open it from the Downloads panel on the project's settings page.
  • The instance's log is at /admin/downloads, under Downloads in the account menu, for instance admins.
• Usage at a glance. Each log opens with:
  • all downloads in the last 30 UTC days, or the retention period if it is shorter, and the share from each source: web sign-in, CLI sign-in, install key or anonymous
  • a bar chart per UTC day with the busiest day
  • the ten busiest versions on a skill's log, skills on a project's log, or projects on the instance's log
• Every download, newest first. Below the figures, a paged list shows each download's time in UTC, skill, version, source, account, the computer for a CLI sign-in, country, IP address and User-Agent.
  • Filter by account, skill or source, and on the instance's log by project. A filter narrows the figures and the chart as well as the list.
  • The list covers every UTC day in the retention period, 50 downloads a page.
• Old records are deleted on their own. The hourly job deletes records older than the retention period. Deleting a skill hides its records at once, and the next run deletes them. Deleting an account keeps its records under its username.

Changed

• Download counts update once an hour. The hourly job adds new downloads to each skill's count, so the count on a skill's page can trail by up to an hour. Counts are never pruned with the records.

v2.0.0

Upgrade notes

Read this before you deploy. This release replaces the install addresses that carried a key with sign-ins through the skillsgist CLI, so every install command, agent prompt and CI job that used a key stops working the moment you upgrade.

• Migration 0005_install_key_prefix.sql replaces every install key with a new sgi_ key. Migrations 0006_cli_logins.sql and 0007_cli_login_grants.sql add the tables for CLI sign-ins.
• The /i/<key> addresses are gone and answer 404. npx skills add https://…/i/<key> commands and the agent prompts copied from private skills' pages stop working.
• Private skills now install with the skillsgist CLI, skillsgist@1.0.0 or later. Run npx skillsgist login <your instance's address> once on each computer, then npx skillsgist add https://…/p/<project>.
• For CI, copy the new key from the project's settings page into a masked secret named SKILLSGIST_INSTALL_KEY, and set SKILLSGIST_HOST to your instance's address. docs/usage.md has a GitHub Actions example.
• The stock npx skills still installs public skills from https://…/p/<project>. It cannot install private ones.
• A repository whose skills-lock.json records an old /i/ address needs those skills reinstalled from the /p/<project> address, because npx skills update can no longer reach the old one.
• Until you upgrade an instance, keep using npx skillsgist@0.4.1 against it.
• Publish tokens (SKILLSGIST_TOKEN) and the publish API are unchanged.

To upgrade with Wrangler, pull and deploy. npm run deploy applies the migrations first:

git pull
npm install
npm run deploy

If the deploy fails after the migrations, finish it before anyone uses the site, or reset the install keys afterward. Until the new Worker is live, the old one is still running and shows the new keys inside its /i/ install commands.

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again and applies the migrations.

npm run verify:cli now runs the skillsgist CLI (npx skillsgist@latest) instead of npx skills. Set SKILLSGIST_CLI to run another build, such as SKILLSGIST_CLI="node ../skillsgist-cli/dist/cli.js".

Added

• Sign a computer in with npx skillsgist login. The CLI shows an eight-letter code and sends you to /device on your instance.
  • After you sign in there and enter the code, the page shows the computer's name, when the request was made and the country it came from, and asks you to check that your terminal shows the same code.
  • You tick the projects the computer may install private skills from, at least one, then Approve or Deny. The terminal finishes the sign-in on its own.
  • A request expires after 10 minutes. Five wrong codes lock code entry for your account for 10 minutes.
  • npx skillsgist whoami shows who a computer is signed in as and for which projects, and npx skillsgist logout signs it out.
• CLI sign-ins on your account page. /me lists every computer you signed in, with the projects it may install from, when it signed in and when it was last used. Sign out stops a computer installing private skills at once.
  • A computer unused for 90 days is signed out on its own and marked Expired. Remove clears it from the list.
  • With no computer signed in, the panel shows the npx skillsgist login command to copy.
• An install key for CI on each project's settings page. Members see an Install key for CI panel there with their sgi_ key, a ready command (SKILLSGIST_HOST=… npx skillsgist add …/p/<project> -g -y) and Reset install key.
  • The key installs only that project's skills and can do nothing else: it cannot sign in, publish or delete.
  • The CLI sends it in the Authorization header, and only to the address in SKILLSGIST_HOST. It never goes in a URL, so it no longer lands in skills-lock.json.

Changed

• Every install command is npx skillsgist add with the project's address. Skill pages, project pages and the agent prompt show https://…/p/<project> to everyone, members and visitors alike, and none of them carries a key.
  • The notes under commands and prompts that warned about a key inside them are gone, because there is no key to leak.
  • The agent prompt runs npx -y skillsgist add <address> --skill <slug> -g -y. A private skill's prompt now installs only on a computer that is signed in for its project.
• Losing access signs computers out. Changing your password, an admin resetting it, and npm run reset-password sign out every computer of that account.
  • On an account's settings page, admins see Install keys and CLI sign-ins with how many of each the account has. Rotate install keys and sign out computers replaces every key and signs every computer out at once.
  • Removing a member from a project, or deleting the project, takes it away from that member's signed-in computers at once.
• Answers that can include private skills are never cached. A project's index and its private skills' downloads are sent with Cache-Control: private, no-store and Vary: Authorization. A key or sign-in that does not cover the project still gets its public skills; the registry answers 401 or 403 only when nothing public matches.
• The README is for people deciding whether skillsgist fits them. Deployment, the custom domain, limits, upgrading and password resets moved to docs/deploy.md. Installing, publishing and roles moved to docs/usage.md, and the architecture and development setup to CONTRIBUTING.md.

v1.5.0

Upgrade notes

This release has no database migration. The deployed Worker changes, so pull and deploy:

git pull
npm install
npm run deploy

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again.

npm run verify:cli now also runs the agent prompt in a terminal, so it needs script: the util-linux one on Linux, or the BSD one that ships with macOS and FreeBSD. Without either, it stops with an error before it starts. The deployed Worker does not need it.

Added

• An agent prompt next to each skill's install command. A skill's page has a Command / Prompt switch above the install box. Command is selected by default and works as before.
  • Prompt shows one sentence to paste into Claude Code or another agent that can run shell commands. It tells the agent to run npx -y skills add <address> --skill <slug> -g -y, read the command's whole output, open the SKILL.md in the directory that output reports, and follow it right away. One paste installs the skill and starts using it.
  • The command in the prompt installs globally, into the home directory (-g). Nothing is written into the project the agent is working in, so no skills-lock.json with the install address lands there. npx -y and the trailing -y keep npx and the CLI from asking anything, and --skill installs only this skill.
  • It uses skills add, which older skills releases also have. npm run verify:cli runs the prompt's command exactly as the page shows it, with the current skills and with skills@1.5.7, inside Claude Code and inside an agent the CLI does not know, and checks that the skill is installed and the project directory stays empty.
  • The prompt is worded in the page's language: English, Simplified Chinese, Traditional Chinese or Japanese. The command inside it is the same in every language.
  • A public skill's prompt always uses the project's public address, even for a signed-in member who has an install key. A private skill's prompt carries your install key. A note under it says so, tells you to paste it only into an agent you trust, and links to the project's Settings to reset the key.
  • The box shows the prompt on one line and cuts it with an ellipsis. Copy still copies the whole sentence.
  • An older version's page shows only the command, because the prompt installs and follows the latest version.
  • The switch is a pair of native radio buttons and needs no JavaScript. In a browser without :has() the switch is hidden, and the command and the prompt show one above the other.

Changed

• A note under a skill's install command when it carries your key. On a skill's page, when the command includes your install key, a note under it says so. It also warns that installing into a code repository records the key in that repository's skills-lock.json, and links to the project's Settings to reset the key. Older versions' pages show it too.

v1.4.0

Upgrade notes

This release has no database migration, and the deployed Worker behaves as in v1.3.0. The new command runs from a clone of the repository, so pulling and installing is enough to get it:

git pull
npm install

npm run deploy works as before if you want the deployed code to match the tag.

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push as usual. To run the new command, clone your copy, then run npm install and npx wrangler login.

Added

• npm run reset-password for a forgotten password. /setup switches itself off once any account exists, so an instance whose only admin forgot the password could only be recovered by editing D1 by hand.
  • npm run reset-password asks for the username and the new password. The password is hidden and asked for twice. npm run reset-password -- alice names the account up front.
  • It writes to the deployed D1 database through Wrangler, so it needs the same Wrangler login as npm run deploy. Add --local to reset a password in the local development database instead.
  • The password is hashed the way the app hashes it, so the new password signs in straight away and the old one stops working. Any account can be reset, admin or member.
  • It refuses an invalid username, a password shorter than 12 characters and a repeat that does not match before it writes anything. An unknown username changes nothing: No user named "alice" in the remote database.
  • Sessions that are already signed in stay signed in. To sign everyone out, change SESSION_SECRET.
  • When an admin can still sign in, nothing changes: they set a new password for any account on that account's settings page. The README's new Reset a forgotten password section covers both.

v1.3.0

Upgrade notes

Read this before you deploy. Migration 0004_membership_publish.sql adds a publishing switch to every project membership and turns it on for every membership that already exists, so everyone who could publish in v1.2 still can. Memberships created after the upgrade start with publishing blocked.

If CI publishes with the API token of an account that you add to a project after upgrading, allow that account's publishing on the project's settings page. Until you do, its PUT answers 403.

To upgrade with Wrangler, pull and deploy. npm run deploy applies the migration first:

git pull
npm install
npm run deploy

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again and applies the migration.

Added

• Per-member publishing. Project admins decide which of their project's members can publish into it.
  • Each member's row on the project's settings page has an Allow publishing or Block publishing button, and a blocked member is tagged Cannot publish.
  • A member added to a project starts with publishing blocked. The Add a member form says so.
  • A blocked member still sees and installs every skill in the project with the same install key. They cannot publish into the project, and they cannot edit, upload to, change the visibility of, move or delete the skills they own there.
  • Project admins and instance admins can always publish, whatever the switch says. The switch is kept through a promotion and a demotion, so a project admin who is made a member again gets back the switch they had.
  • The publish page lists only the projects you can publish into. When an admin has blocked you in all of them, it says that each project's admins decide who publishes, instead of asking you to join a project.
  • The API refuses a blocked member with 403, for new versions and republishes of their own skills too: {"error":"forbidden","message":"You are not allowed to publish to <project>. Ask one of its admins to allow it."}

v1.2.0

Upgrade notes

This release has no database migration. To upgrade with Wrangler, pull and deploy:

git pull
npm install
npm run deploy

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again.

wrangler.jsonc no longer carries a placeholder database_id, because Wrangler finds the D1 database and the R2 bucket by name. If you put your own database_id into wrangler.jsonc, the merge may conflict on that line. Keep your line.

Added

• The web UI in four languages: English, Simplified Chinese, Traditional Chinese and Japanese.
  • The language comes from the browser's Accept-Language, or from the language menu in the footer, which remembers the choice for a year. Browsers set to Taiwan, Hong Kong, Macau or zh-Hant get Traditional Chinese in Taiwan wording; every other Chinese variant gets Simplified Chinese. Anything else gets English.
  • Dates and counts are formatted for the chosen language, and error messages on the pages, upload errors included, are shown in it.
  • Page addresses are the same in every language, so a shared link opens in each reader's own language. Install commands, the discovery index and the API, error messages included, do not change. Skill content and names are never translated.
• Menus and confirmations close on their own. Escape, a press outside, or moving focus away closes an open menu or confirmation. Without JavaScript they work as before.

Changed

• Deploying by hand no longer edits tracked files. The README's wrangler d1 create and wrangler r2 bucket create commands pass --no-update-config, and wrangler.jsonc has no account-specific IDs, so a fresh clone deploys as it is.
• Custom domains are added in the Cloudflare dashboard, under the Worker's Settings → Domains & Routes, instead of as a routes entry in wrangler.jsonc. Deploys leave a dashboard Custom Domain alone.

v1.1.0

Upgrade notes

Read these before you deploy. Migration 0003_projects.sql moves every existing skill and every account into a new project called Default, whose address is default. Three things change:

• Install keys are reissued. Each person now has one install key per project, and the migration generates new ones, so every /i/<key> command from v1.0 stops working. Each person copies their new command from /p/default or from the project's settings page.
• The publish API gains a project. PUT /api/skills/<name> is now PUT /api/projects/<project>/skills/<name>; for existing skills that is /api/projects/default/skills/<name>. Update CI scripts. Existing API tokens keep working.
• Skill pages move under their project. /s/<name> is now /p/<project>/s/<name>. Old links no longer resolve.

Everyone who had an account becomes a member of Default. Instance admins stay instance admins.

To upgrade with Wrangler, pull and deploy. npm run deploy applies the migration first:

git pull
npm install
npm run deploy

If you deployed with the Deploy to Cloudflare button, merge this repository into your copy and push; Workers Builds deploys again and applies the migration. Keep the database_id in your wrangler.jsonc if the merge touches it.

Added

• Projects. Every skill belongs to one project, and people are members of projects.
  • Each membership has its own role. Project admins manage every skill in the project, rename it, and add, remove, promote and demote its members, without instance-wide rights.
  • Each person has one install key per project, and it installs only that project's skills. Reset it from the project's settings page.
  • /p/<project> is a project's home page: the viewer's install command, a search over its skills and a grid of them. Public skills install with no key: npx skills add https://<your-domain>/p/<project>.
  • A project has a name you can change at any time and an address, fixed at creation, that appears in its page, install and API addresses.
  • /projects lists projects with your role, their skill count and their member count. Instance admins create projects at /projects/new and can delete a project once it has no skills.
  • A skill can move to another project with its versions, owner, visibility and download count, unless the target already has a skill with its name.
• Download counts. Every skill card and skill page shows how many times the skill has been downloaded, to signed-in users.
  • Counted: every archive served to npx skills add, and every Download zip from the browser, for the latest version or a numbered one.
  • Not counted: page views, index fetches, HEAD requests, and refused requests.

v1.0.0

The first public release of skillsgist: a private Agent Skills registry you self-host on Cloudflare and install from with the stock npx skills add.

Highlights

• One-click deploy. The Deploy to Cloudflare button copies the repository, creates the D1 database and R2 bucket, asks for SESSION_SECRET, applies migrations and deploys. Deploying by hand with Wrangler works too.
• The stock CLI is the client. skillsgist serves the skills.sh discovery protocol, so npx skills add works with no custom CLI, plugin or fork.
• Private by default. Every skill starts private and becomes public only by an explicit per-skill switch. Private installs use a per-user install key that can do nothing but install.
• Publish from anywhere. Upload a .zip, a .tar.gz or a single SKILL.md in the browser, edit SKILL.md in place, or publish from CI with the idempotent PUT /api/skills/:name.
• Versions you can trust. Versions are immutable and numbered, artifacts are content-addressed and verified by the CLI, and republishing older content rolls back.
• Browse and manage. Rendered SKILL.md pages, file lists, version history and search, plus admin and member roles with account management in the browser.
• Plain and safe web pages. Pages are server-rendered, work without JavaScript and ship a strict Content-Security-Policy.

Getting started

See Deploy in the README.

Known limits

• An upload may be at most 2 MB, unpack to at most 8 MB and contain at most 200 files, to fit the Workers Free plan's CPU budget. On Workers Paid these can be raised.
• Resetting a password does not end browser sessions that are already signed in; sessions last up to 30 days. Delete the account or rotate SESSION_SECRET to end them immediately.