teamskills docs
Everything you need to install the CLI, add skills to your agents, write your own, and share them with the world or just your team.
Introduction
teamskills is a registry and CLI for AI agent skills. A skill is a folder with a SKILL.md file that teaches an agent how to do something. Publish it once, version it with semver, and install it into every agent you use — Claude Code, OpenCode, Cursor, Codex and more.
Publish
Push a folder and get a versioned, shareable skill.
Install
One command writes it into every detected agent.
Share
Public, private, or restricted to a team.
Install the CLI
The CLI is a Node.js package. You need Node 20 or newer. Install it globally so the teamskills command is on your PATH.
# macOS / Linux / WSL (no Node needed — the script installs via npm)
curl -fsSL https://teamskills.space/install.sh | sh
# Windows PowerShell
irm https://teamskills.space/install.ps1 | iex
# Already have Node? Use npm directly
npm i -g @muhadif/teamskills
teamskills --version No global install? Run it per-project with npx teamskills <command>.
Quickstart
From nothing to an installed skill in under a minute.
# 1. Sign in through your browser
teamskills login
# 2. Find something to install
teamskills search pdf
# 3. Install it into every agent we detect
teamskills install anthropics/pdf-tools@latestinstall detects which agents are on your machine and writes the skill into each one. Use --agent to target specific agents instead.
Authentication
Signing in opens your browser, the same flow used by gh and wrangler. The browser hands back a short-lived session and the CLI trades it for a long-lived token, which is saved to ~/.config/teamskills/config.json with owner-only permissions.
teamskills login # magic link via your browser
teamskills login --google # use Google instead
teamskills login --no-open # print the URL, don't launch a browser
teamskills login --token tsk_… # CI: sign in with a token
teamskills token create ci # mint a token (shown once; --days N expires it)
teamskills token list # name, expiry and last use
teamskills whoami # show the signed-in account
teamskills logout # clear the saved token
# A browser login saves a long-lived "cli" token, not the 15-minute
# session the callback hands back — sessions cannot be refreshed by the CLI.
# Each login mints another one; revoke stale ones from `token list`.Environment variables
Useful in CI or when you don't want a config file on disk.
export TEAMSKILLS_API=https://teamskills.space
export TEAMSKILLS_TOKEN=<access-token>
export TEAMSKILLS_CONFIG=/path/to/config.json| Variable | Purpose |
|---|---|
| TEAMSKILLS_API | Override the registry API base URL. |
| TEAMSKILLS_TOKEN | Supply an access token directly. |
| TEAMSKILLS_CONFIG | Use a custom config file path. |
Using skills
Reference any skill as owner/slug. Add a version or tag after @ to control exactly what you get.
teamskills install owner/skill # latest version
teamskills install owner/[email protected] # pin an exact version
teamskills install owner/skill@stable # follow a tag
teamskills install owner/skill@latest # follow the newest release
teamskills install owner/skill@sha256:… # pin an immutable digestWhere skills land
By default a skill is installed into the current project (./.claude/skills/…). Use --global to install into your home directory so it's available everywhere, or --dir for an exact path.
teamskills install owner/skill --agent claude,cursor
teamskills install owner/skill --agent auto # default: detect installed
teamskills install owner/skill --global # user-wide instead of project
teamskills install owner/skill --dir ./my/skills # explicit destinationSearch and inspect before you install:
teamskills search pdf
teamskills info anthropics/pdf-toolsWriting a skill
A skill is just a folder with a SKILL.md at its root. Add optional frontmatter for metadata and write the instructions below it in Markdown. Anything else in the folder — scripts, references, assets — is packed along with it.
---
name: pdf-tools
description: Extract text, merge, and split PDF files.
version: 1.4.2
license: MIT
---
# PDF tools
Use this skill when the user asks to work with PDF files.
## Usage
```bash
pdf-tools extract report.pdf
```| Frontmatter | Required | Notes |
|---|---|---|
| name | No | Defaults to the directory name. |
| description | No | Shown in search results and on the skill page. |
| version | No | Semver. Defaults to 0.1.0. |
| license | No | SPDX identifier. |
Publishing
Publish a local folder, or import one straight from GitHub. Publishing a folder whose owner/slug already exists adds a new version, and the newest one becomes @latest.
# publish the skill in the current directory.
# The first publish asks for the owner (you or a team), name, description,
# visibility, categories and version — each defaulting to what SKILL.md says.
teamskills publish .
# answer everything up front to skip the prompts
teamskills publish ./pdf-tools --name "PDF tools" --category pdf,docs
# add a version to a skill you already published, and move a tag to it
teamskills publish ./pdf-tools --version 1.5.0 --tag stable
# share with your team only
teamskills publish . --team acme --visibility team
# push a proposal: stored and installable by ref, but not live
teamskills publish . --draft --version 1.5.0
# publish a proposal — the merge step that moves latest onto it
teamskills promote owner/[email protected]
# CI: take every default, never prompt
teamskills publish . --yesImport from a URL
Importing happens server-side, so it works for public repos and raw SKILL.md links.
# import from a GitHub repository
teamskills import https://github.com/owner/repo
# a monorepo subdirectory, on a specific branch
teamskills import https://github.com/owner/repo --ref main --path skills/pdf
# import a single raw SKILL.md
teamskills import https://example.com/SKILL.mdVisibility
Anyone can find and install it.
Visible only to members of the owning team.
Visible only to you.
Pass --visibility team together with --team <slug> to publish under a team.
Managing a skill
Star, retag, move, or delete a skill you own without republishing it.
teamskills star owner/skill # star it
teamskills tag owner/skill beta --version 1.2.0 # point a tag at a version
teamskills visibility owner/skill team --team acme # share with a team
teamskills delete owner/skill # asks first; --yes in scriptsTeams
Teams give a group a shared, private namespace for skills. Create one, invite people by email or share an invite code, then publish with --team.
teamskills team create "Acme"
teamskills team list
teamskills team invite acme --email [email protected] --role editor
teamskills team role acme @teammate admin
teamskills team join <invite-code>
teamskills team members acmeCommand reference
Every command also supports --help. A global --api <url> flag points the CLI at a different registry.
| Command | Description |
|---|---|
| login | Sign in through the browser (magic link or --google). Saves a long-lived token. |
| logout | Sign out and remove the saved token. |
| whoami | Print the signed-in account. |
| search [query] | Search public skills (--owner, --project). |
| info <owner>/<slug> | Show a skill, its versions and tags. |
| install <owner>/<slug>[@ref] | Install a skill into one or more agents. |
| publish [path] | Publish a new skill, or add a version to one you own (--draft to keep it unpublished). |
| promote <owner>/<slug>@<version> | Publish a pushed proposal: the merge step. |
| import <url> | Import a skill from GitHub or a raw URL. |
| agents | List supported agents and which are installed. |
| team create|list|invite|join|members|role | Manage teams and membership. Roles: viewer, editor, admin. |
Supported agents
Run teamskills agents to see which are installed on your machine (marked ●) and where each skill will be written.
| Agent | Project path | Global path (~) |
|---|---|---|
| claude | .claude/skills | .claude/skills |
| opencode | .opencode/skills | .config/opencode/skills |
| cursor | .cursor/skills | .cursor/skills |
| codex | .codex/skills | .codex/skills |
| windsurf | .windsurf/skills | .windsurf/skills |
| gemini | .gemini/skills | .gemini/skills |
| copilot | .github/skills | .github/skills |
| continue | .continue/skills | .continue/skills |
| cline | .cline/skills | .cline/skills |
| roo | .roo/skills | .roo/skills |
| augment | .augment/skills | .augment/skills |
| kilocode | .kilocode/skills | .kilocode/skills |
| amp | .amp/skills | .config/amp/skills |
| droid | .factory/skills | .factory/skills |
| agents | .agents/skills | .agents/skills |
API reference
The registry is a JSON API. Authenticated requests send Authorization: Bearer <token>. Downloads return a gzipped tarball; everything else returns JSON.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/skills | List and search skills visible to the caller (q, tag, sort, limit, offset; returns total). |
| GET | /api/skills/:owner/:slug | Skill detail with versions and tags. |
| GET | /api/skills/:owner/:slug/download | Download the gzipped tarball (?ref=version|tag|sha256:digest). |
| GET | /api/skills/:owner/:slug/content | Latest SKILL.md, file list, and your saved draft. |
| GET | /api/skills/:owner/:slug/files | Read one file from the latest tarball for preview (?path=, ?ref=). |
| GET | /api/skills/:owner/:slug/versions | List versions, published or not. |
| GET | /api/skills/:owner/:slug/tags | List mutable tags. |
| GET | /api/skills/:owner/:slug/stats | Install totals; per-day series for owners. |
| GET | /api/skills/:owner/:slug/badge.svg | README badge (?metric=installs|stars|version). |
| GET | /api/skills/:owner/:slug/badge.json | The same badge as a shields.io endpoint payload. |
| POST | /api/skills | Publish a new skill (auth required). |
| PUT | /api/skills/:owner/:slug | Rename, re-describe, change visibility, or move a skill to a team (owner). |
| POST | /api/skills/:owner/:slug/versions | Publish a new version (draft: true stores it unpublished). |
| POST | /api/skills/:owner/:slug/versions/:version/publish | Promote an unpublished version (owner). |
| PUT | /api/skills/:owner/:slug/draft | Save a SKILL.md draft (owner). |
| DELETE | /api/skills/:owner/:slug/draft | Discard a saved draft (owner). |
| PUT | /api/skills/:owner/:slug/tags/:tag | Move a tag to a version. |
| DELETE | /api/skills/:owner/:slug | Delete a skill you own. |
| POST | /api/import | Import from GitHub or a raw URL. |
| GET | /api/leaderboard | Most-installed skills. |
| GET | /api/projects | Projects visible to the caller (q, limit, offset; returns total). |
| GET | /api/teams | Teams the caller belongs to (q, limit, offset; returns total). |
| POST | /api/teams | Create a team. |
| POST | /api/teams/:slug/invites | Invite someone as viewer, editor or admin. |
| PUT | /api/teams/:slug/members/:userID | Change a member's role. |
| GET | /api/users/:handle | Public user profile. |
| POST | /api/tokens | Create a personal access token (auth required); the value is shown once. |
| GET | /api/tokens | List your personal access tokens. |
| DELETE | /api/tokens/:id | Revoke a personal access token. |
Troubleshooting
“not logged in” when publishing
Run teamskills login, or set TEAMSKILLS_TOKEN.
“could not detect any agent”
Pass --agent explicitly, e.g. --agent claude,cursor. See teamskills agents.
“unknown agent”
Check the agent name against the table above.
Checksum mismatch on install
The download was corrupted or truncated. Retry; if it persists, the published artifact may be stale.
CLI not found after install
Ensure your npm global bin directory is on PATH, or run it with npx teamskills.
Ready to publish your first skill?
Install the CLI, sign in, and share a skill with the world — or just your team.