Skillshare TUI

Development CLI for the Skillshare registry.

Examples

bun run index.ts
bun run index.ts login
bun run index.ts login local
bun run index.ts list
bun run index.ts install
bun run index.ts install "Prompt Lint"
bun run index.ts update
bun run index.ts update "Prompt Lint" --dry-run
bun run index.ts update 12 --target ./installed
bun run index.ts upload ./examples/prompt-lint --version 0.1.0
bun run index.ts install 12 0.1.0 --target ./installed
bun run index.ts install --skill-version-id 42 --target ./installed

Connected agents

skillshare agents listen lets Skillshare run Claude Code (claude) or Codex (codex) sessions on this computer. Start a session under Sessions in Skillshare and keep talking to the agent there; Teams 👀 sessions go to the computer chosen under Connected agents. The listener reports the installed agents with their models and reasoning levels. Agents use the login you already have in claude and codex, and run with your full local permissions and configuration, without permission prompts.

Codex runs as codex app-server and Claude Code with stream-json input and output. The agent keeps running between your messages and stops after 15 quiet minutes; the next message resumes the same Codex thread or Claude Code session. Sessions need CLI 1.10.0 or newer. Images attached to messages reach the agent from CLI 1.10.2: the listener downloads them to a temp directory that it removes when the session closes.

skillshare agents status
skillshare agents listen --workdir ~/Research
skillshare agents listen --name desktop --max-concurrency 2

The listener updates itself: when Skillshare releases a newer CLI, it downloads it into ~/.config/skillshare/versions (on Windows %APPDATA%\skillshare\versions) and restarts on it once no turn is running. --no-update turns that off.

To keep it running without a terminal, install it as a background service that starts at every login: a launchd agent on macOS, a systemd user service on Linux and a scheduled task on Windows. It takes the same options as listen; run it again to change them.

skillshare agents service install --workdir ~/Research
skillshare agents service status
skillshare agents service logs --lines 100
skillshare agents service uninstall

On Windows, run these in PowerShell or Command Prompt as yourself, not as administrator. Use npx.cmd instead of npx where PowerShell's script policy blocks npx, and pass a Windows working directory such as --workdir ~\Projects. The service is the scheduled task "Skillshare Agents", which starts at logon without a console window. Agents installed as npm shims (claude.cmd, codex.cmd) are started through cmd.exe with every argument quoted; Claude Code gets the session instructions as a file.

--sandbox keeps every agent read-only. Claude Code may only read files, search the web and use the Skillshare MCP; Codex runs in its read-only sandbox. A profile can do the same with "sandbox": true.

Optional named profiles in ~/.config/skillshare/agents.json set a working directory and extra arguments. For Claude Code the arguments are added to claude; for Codex only configuration overrides (-c, --config, --enable, --disable) apply to codex app-server. Only the name, agent, model, reasoning and the working directory's last segment are sent to Skillshare.

{ "profiles": [
  { "name": "piq-opus-high", "agent": "claude", "model": "opus", "reasoning": "high",
    "workdir": "~/Research/piq-modules", "args": ["--add-dir", "~/Research/piq-projects"] }
] }

Teams MCP

Starting with 1.7.0, skillshare teams login opens a dedicated local browser profile, connects your own Teams account to Skillshare and verifies the connection. Sign in with the same Microsoft account as Skillshare. The server refreshes captured tokens in the background. teams watch renews an expired Microsoft grant through local browser SSO; agents listen does the same while it runs, so a computer that runs agents needs no separate teams watch (--no-teams-watch turns it off). Keep that process running for automatic recovery beyond the SPA refresh token lifetime; another interactive CLI login is needed only when SSO cannot complete, for example MFA.

skillshare login
skillshare teams login
skillshare teams status
skillshare teams test
skillshare teams watch
skillshare teams access fullAccess
skillshare teams upload ./report.pdf
skillshare teams download '<file-webUrl-or-download-link>' --output ./report.pdf
skillshare teams access readOnly
skillshare teams logout

Starting with 1.8.1, Teams uses the Microsoft account object id that Skillshare records at web sign-in, not the Skillshare user id. If the server does not know it yet, teams login opens one more Skillshare sign-in in the browser to link the account.

Use teams login local for localhost or --server <https-origin> for another host. login accepts --server too. Browser options: --browser chrome|msedge|chromium, --headless, and --browser-profile <dedicated-profile-directory>. Chrome is the default on macOS/Linux, Edge on Windows; bundled Chromium needs npx playwright install chromium first. See Teams MCP for permissions, Microsoft session lifetime and file-tool differences in the hosted server.

Behavior

Starting with 1.9.0:

• agents listen and agents status run Claude Code and Codex sessions from Skillshare on this computer (see Connected agents); --sandbox keeps them read-only.
• Commands print readable text. Scripts that parsed JSON from whoami, list, show, upload, pages list|show|runtime|upload|secrets or teams status|test|upload must add --json; with --json progress goes to stderr and stdout contains only JSON.
• show accepts a skill name as well as an id.
• pages upload refuses build output folder names such as dist or build without --slug, says whether it creates or replaces a page, refuses pages owned by someone else unless you are an admin, and prints the page URL.

Starting with 1.8.0:

• install and update download into a staging directory first, so a failed transfer leaves the existing install untouched. Files that a new version no longer contains are removed.

• installed.json records a SHA-256 manifest of installed files. update skips installs with local changes and install refuses to overwrite them, or a directory that Skillshare did not install, unless you confirm interactively or pass --force. Installs recorded by older versions are not checked until they are updated once.

• Interactive mode shows the signed-in user and server, checks installed skills in parallel, and reports removed skills or failed checks as warnings instead of stopping.

• login prints the sign-in URL in case no browser opens, and stops waiting after 5 minutes.

• Unknown options are rejected with a suggestion. skillshare <command> --help, skillshare help <command> and skillshare --version are available.

• Starting with 1.6.2, login, git configure and API commands without a stored session default to https://skillshare.quadientcloudpreprod.eu. login local and git configure local still select http://localhost:5050.

• Existing sessions keep their saved server. After preprod cutover, run skillshare login again to replace a UAT session with a preprod session; stored tokens are not reused across hosts.

• Uploaded/installed records retain their registry URL. Legacy records without a URL still belong to UAT and are not silently reassigned to preprod.

• Upload and publish commands show progress while scanning and reading local files, then keep a timed upload status visible until the registry call finishes.

• update reads the centralized install registry and refreshes recorded installs to the latest published registry versions.

• update can be narrowed to one skill or one target directory, and --dry-run prints planned changes without downloading or overwriting files.

• Interactive mode now checks for recorded installs with newer published versions and offers updating them before showing the main action menu.

Current TUI Flow

flowchart TD
  A[Start: skillshare] --> B{Command provided?}

  B -- No --> C[runInteractive]
  B -- Yes --> D{Which command?}

  D -->|login local| E[login LOCAL_URL]
  D -->|login| F[login DEFAULT_URL]
  D -->|logout| G[logoutSession]
  D -->|whoami list show upload install update| H[createClient using active baseUrl]

  C --> I[resolveActiveBaseUrl]
  I --> J[ensureInteractiveLogin]
  J --> K{Stored session exists?}
  K -- No --> F
  K -- Yes --> L{Refresh token still valid?}
  L -- No --> F
  L -- Yes --> M[createClient and GET /api/auth/me]
  M --> N{Session still accepted?}
  N -- No --> F
  N -- Yes --> O[Interactive menu ready]

  E --> P[Start PKCE and callback server]
  F --> P
  P --> Q[Open browser to /api/cli/login]
  Q --> R[Wait for local callback with code and state]
  R --> S[POST /api/cli/token]
  S --> T[Store session.json]
  T --> O

  O --> U{Current directory contains SKILL.md?}
  U -- Yes --> V{Upload current directory now?}
  V -- Yes --> W[runInteractiveUpload]
  V -- No --> X[Choose action]
  U -- No --> X

  X --> Y{Install, Update or Upload?}
  Y -->|Install| Z[runInteractiveInstall]
  Y -->|Update| U0[updateInstalledSkills]
  Y -->|Upload| W

  Z --> Z1[GET /api/skills]
  Z1 --> Z2[Choose skill or resolve skillRef]
  Z2 --> Z3[GET skill detail]
  Z3 --> Z4[Choose version or use provided version]
  Z4 --> Z5[Choose project/global scope]
  Z5 --> Z6[Choose agents]
  Z6 --> Z7[GET version detail]
  Z7 --> Z8[POST download audit]
  Z8 --> Z9[Write files to install targets]
  Z9 --> Z10[Update installed.json]
  Z10 --> END[Done]

  U0 --> U1[Read installed.json for active baseUrl]
  U1 --> U2[GET skill detail for each installed target]
  U2 --> U3{Latest differs from installed version?}
  U3 -- No --> U4[Skip target]
  U3 -- Yes --> U5[GET latest version detail]
  U5 --> U6[POST download audit]
  U6 --> U7[Overwrite target files]
  U7 --> U8[Update installed.json]
  U4 --> END
  U8 --> END

  W --> W1[Load local skill context]
  W1 --> W2{uploaded.json has skillId for this directory?}

  W2 -- No --> W3[Prompt initial version]
  W3 --> W4[createSkillFromDirectory]
  W4 --> W5[POST create skill]
  W5 --> W6[GET created skill detail]
  W6 --> W7[Update uploaded.json]
  W7 --> END

  W2 -- Yes --> W8[GET existing skill detail]
  W8 --> W9{Local version differs from latest?}
  W9 -- Yes --> W10{Download latest first?}
  W10 -- Yes --> W11[GET latest version detail]
  W11 --> W12[POST download audit]
  W12 --> W13[Overwrite local files and update installed.json]
  W13 --> END

  W10 -- No --> W14[Prompt new version]
  W9 -- No --> W14
  W14 --> W15[publishSkillFromDirectory]
  W15 --> W16[POST publish version]
  W16 --> W17[GET updated skill detail]
  W17 --> W18[Update uploaded.json]
  W18 --> END

State Storage

Session storage paths:

• macOS/Linux: ~/.config/skillshare/session.json
• Windows: %APPDATA%\\skillshare\\session.json

Centralized TUI state:

• uploaded.json sits next to session.json and stores uploaded skill directories plus the registry skill/version they map to.
• installed.json sits next to session.json and stores installed target directories plus the installed skill/version for each target.
• New installs and uploads no longer need to create skillshare.metadata.json in the target directories.

Authentication

Bearer token precedence:

• --token <token> has the highest priority.
• SKILLSHARE_TOKEN is used when --token is not provided.
• Stored interactive session is used only when neither explicit token source is present.

Example non-interactive usage with a personal access token:

export SKILLSHARE_TOKEN="<personal-access-token>"
npx @quadient/skillshare whoami

Register the default preprod or local SkillShare host as a generic OAuth provider in Git Credential Manager 2.0.931 or newer:

skillshare git configure
skillshare git configure local

Remove only the URL-scoped SkillShare registration with skillshare git unconfigure [local]. The first Git clone opens the browser login; no SkillShare personal access token needs to be created.

Update recorded installs to the latest versions:

npx @quadient/skillshare update
npx @quadient/skillshare update "Prompt Lint" --dry-run
npx @quadient/skillshare update 12 --target ./installed

Publish an authenticated static page. The upload replaces the page's complete content, and the directory must contain index.html at its root. By default the directory name is used as the page slug; build output folders such as dist need --slug:

npx @quadient/skillshare pages upload ./release-notes
npx @quadient/skillshare pages upload ./site --slug release-notes
npx @quadient/skillshare pages list
npx @quadient/skillshare pages show release-notes

The page is then available at https://skillshare.quadientcloudpreprod.eu/p/release-notes/ after SSO sign-in.

Package Distribution

The CLI is prepared for publishing as @quadient/skillshare.

Recommended invocation:

npx @quadient/skillshare
bunx @quadient/skillshare

Packaging checks:

bunx tsc --noEmit
npm run build
npm pack --dry-run

Publishing from the repo root:

bun run publish:tui:dry-run
bun run publish:tui
bun run publish:tui -- --otp 123456

The publish script builds tui/, validates the packed files with npm pack --dry-run, and only then runs npm publish.

Pages applications

skillshare pages upload <directory> --slug <slug> accepts static sites or Wrangler JSON/JSONC projects. The CLI bundles Worker dependencies locally; install them and build frontend assets before uploading. Inspect process status and logs with skillshare pages runtime <slug>. Pages are served below /p/<slug>/, so use that base path when building assets. Runtime data survives content replacement.

Manage the write-only secrets an application reads through SKILLSHARE_SECRETS (page owner or admin only). set reads the value from piped stdin or a masked prompt, so it never appears in shell history; the running app restarts to pick up changes:

skillshare pages secrets list my-app
skillshare pages secrets set my-app API_TOKEN
printf %s "$TOKEN" | skillshare pages secrets set my-app API_TOKEN
skillshare pages secrets delete my-app API_TOKEN

Local Pages development (1.6.0+)

Run a celld application without a SkillShare server, repository checkout, Docker, cloud storage account or CLI login:

bunx @quadient/skillshare@^1.6.0 pages dev . --slug my-app

The directory must contain one wrangler.json or wrangler.jsonc. The CLI downloads and verifies celld 0.4.1 on first use, caches it under ~/.cache/skillshare/celld, and uses its packaged esbuild. Supported hosts are macOS Apple Silicon and Linux x64/ARM64; Windows users can use WSL2. --celld <executable> or CELLD_EXECUTABLE selects an existing installation.

The default URL is http://127.0.0.1:8787/p/my-app/. The proxy removes the Page prefix and adds the same X-Skillshare-* request headers as SkillShare. The development revision is 0. The toolbar offers four local users covering every role combination: Alice (owner), Bob (neither role), Charlie (admin), and Dana (owner and admin). Each option shows explicit isOwner and isAdmin values, and each browser can select its own user. Customize the first user with --user-id, --user-name and --user-email. This is simulated local identity, not a real SSO login. Listeners bind only to loopback.

The proxy filters SkillShare authentication cookies and Authorization on ordinary routes, scopes application cookies and redirects to the Page, and supports HTTP streaming and WebSockets. /api/bypass-sso/* preserves Authorization but forwards no cookies or user identity, matching hosted Pages. Application vars and resource bindings still come from Wrangler. Host cloud credentials and CLI tokens are not passed to the celld process.

For a project with a build step (React/Vite, for example):

bunx @quadient/skillshare@^1.6.0 pages dev dist \
  --watch-dir . --build "bun run build" --slug my-app --port 8787

--build runs in --watch-dir before the first start and after source changes. The command is executed through your shell. The build must produce the complete application directory, including Wrangler configuration, Worker and assets. Source edits are debounced and builds are serialized. The output directory, node_modules, .git, .celld, .wrangler, .skillshare, dist subdirectories and coverage are ignored to avoid rebuild loops. Use a dedicated output directory; do not write generated files alongside watched source files.

After a successful build the CLI gracefully restarts celld and reloads open pages once the new node is ready. Local resources persist in the application's .celld/ directory. Do not delete that directory in your build script. A build failure leaves the previous node serving; a celld startup failure leaves the proxy available with an error page. Fixing a watched source file retries the build/start. The terminal shows errors. Ctrl+C stops the watcher, proxy and child processes.

Browser reload uses a script injected into HTML and a same-origin SSE connection. This is full-page reload, not React HMR. A CSP that disallows same-origin scripts or connections must be adjusted for local development or the page reloaded manually. The /__skillshare_dev/ path is reserved for local development controls. This command does not implement the SkillShare catalog, actual SSO or cloud deployment.

Worker user directory (1.6.1)

Authenticated requests in pages dev include X-Skillshare-Users-Url and X-Skillshare-Users-Token. A Worker can fetch the URL with the token in the X-Skillshare-Users-Token request header to read the four local users. Each entry contains id, displayName, email, isAdmin and isOwner. The hosted backend uses the same contract for active SkillShare users. These capabilities stay in the Worker and are not injected on api/bypass-sso/* requests. See the Worker example.