Skip to content
Documentation

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.

terminal
# 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.

terminal
# 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@latest

install 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.

terminal
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.

shell
export TEAMSKILLS_API=https://teamskills.space
export TEAMSKILLS_TOKEN=<access-token>
export TEAMSKILLS_CONFIG=/path/to/config.json
VariablePurpose
TEAMSKILLS_APIOverride the registry API base URL.
TEAMSKILLS_TOKENSupply an access token directly.
TEAMSKILLS_CONFIGUse 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.

terminal
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 digest

Where 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.

terminal
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 destination

Search and inspect before you install:

terminal
teamskills search pdf
teamskills info anthropics/pdf-tools

Writing 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.

SKILL.md
---
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
```
FrontmatterRequiredNotes
nameNoDefaults to the directory name.
descriptionNoShown in search results and on the skill page.
versionNoSemver. Defaults to 0.1.0.
licenseNoSPDX 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.

terminal
# 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 . --yes

Import from a URL

Importing happens server-side, so it works for public repos and raw SKILL.md links.

terminal
# 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.md

Visibility

public

Anyone can find and install it.

team

Visible only to members of the owning team.

private

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.

terminal
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 scripts

Teams

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.

terminal
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 acme

Command reference

Every command also supports --help. A global --api <url> flag points the CLI at a different registry.

CommandDescription
loginSign in through the browser (magic link or --google). Saves a long-lived token.
logoutSign out and remove the saved token.
whoamiPrint 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.
agentsList supported agents and which are installed.
team create|list|invite|join|members|roleManage 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.

AgentProject pathGlobal 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.

MethodEndpointDescription
GET/api/skillsList and search skills visible to the caller (q, tag, sort, limit, offset; returns total).
GET/api/skills/:owner/:slugSkill detail with versions and tags.
GET/api/skills/:owner/:slug/downloadDownload the gzipped tarball (?ref=version|tag|sha256:digest).
GET/api/skills/:owner/:slug/contentLatest SKILL.md, file list, and your saved draft.
GET/api/skills/:owner/:slug/filesRead one file from the latest tarball for preview (?path=, ?ref=).
GET/api/skills/:owner/:slug/versionsList versions, published or not.
GET/api/skills/:owner/:slug/tagsList mutable tags.
GET/api/skills/:owner/:slug/statsInstall totals; per-day series for owners.
GET/api/skills/:owner/:slug/badge.svgREADME badge (?metric=installs|stars|version).
GET/api/skills/:owner/:slug/badge.jsonThe same badge as a shields.io endpoint payload.
POST/api/skillsPublish a new skill (auth required).
PUT/api/skills/:owner/:slugRename, re-describe, change visibility, or move a skill to a team (owner).
POST/api/skills/:owner/:slug/versionsPublish a new version (draft: true stores it unpublished).
POST/api/skills/:owner/:slug/versions/:version/publishPromote an unpublished version (owner).
PUT/api/skills/:owner/:slug/draftSave a SKILL.md draft (owner).
DELETE/api/skills/:owner/:slug/draftDiscard a saved draft (owner).
PUT/api/skills/:owner/:slug/tags/:tagMove a tag to a version.
DELETE/api/skills/:owner/:slugDelete a skill you own.
POST/api/importImport from GitHub or a raw URL.
GET/api/leaderboardMost-installed skills.
GET/api/projectsProjects visible to the caller (q, limit, offset; returns total).
GET/api/teamsTeams the caller belongs to (q, limit, offset; returns total).
POST/api/teamsCreate a team.
POST/api/teams/:slug/invitesInvite someone as viewer, editor or admin.
PUT/api/teams/:slug/members/:userIDChange a member's role.
GET/api/users/:handlePublic user profile.
POST/api/tokensCreate a personal access token (auth required); the value is shown once.
GET/api/tokensList your personal access tokens.
DELETE/api/tokens/:idRevoke 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.