CtrlK
BlogDocsLog inGet started
Tessl Logo

kumar/tessl-setup

Personal Tessl setup guide — CLI reference for creating plugins/skills, publishing, installing, running evals, and navigating the full plugin lifecycle.

76

Quality

95%

Does it follow best practices?

Impact

—

No eval scenarios have been run

SecuritybySnyk

Risky

Do not use without reviewing

Overview
Quality
Evals
Security
Files

SKILL.mdskills/tessl-basics/

name:
tessl-basics
description:
Use for Tessl concepts and consumer-side operations — what a plugin is, how skills work, auth, project setup, and installing/updating/uninstalling plugins from the registry. Triggers on: "install a plugin", "tessl login", "tessl init", "update plugins", "what is a plugin", "how does tessl work", "authenticate with tessl".

Tessl Basics

What is Tessl

Tessl is a registry and toolchain for agent skills and plugins. Key concepts:

  • Plugin — versioned package in the registry. Contains skills, rules, or MCP servers. Has a .tessl-plugin/plugin.json manifest. This is the unit of distribution.
  • Skill — a SKILL.md file giving an agent reusable instructions. Lives at skills/<skill-name>/SKILL.md inside a plugin.
  • Rules — always-loaded guidance for the agent (steering).
  • MCP servers — declared via a .mcp.json at plugin root. Tessl wires them into each agent's native MCP config on install.
  • Workspace — registry namespace (e.g. kumar). Run tessl org list or tessl workspace list to find yours.
  • Project — a local directory linked to Tessl via tessl.json. Required for evals.

Plugin directory layout

my-plugin/
├── .tessl-plugin/
│   └── plugin.json          # name, version, description, private
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── rules/                   # optional — always-on rules
├── .mcp.json                # optional — MCP servers
└── evals/                   # optional — eval scenarios

CLI vs MCP — When to Use Which

Use the CLI (tessl <cmd>) for:

  • Creating, linting, publishing plugins and skills
  • Installing/updating/uninstalling plugins
  • Running evals and reviews
  • Managing workspaces, API keys, projects
  • Launching skills with agents
  • Any write operation or lifecycle management

Use the MCP server (tessl mcp start) for:

  • Giving a coding agent (Cursor, Claude Code, Codex, etc.) access to search and install registry plugins mid-session — without leaving the agent
  • Checking auth and sync status from inside an agent session
  • The MCP exposes 5 tools only: login, search, install, uninstall, status

Configure MCP for your agent:

tessl init --agent claude-code    # sets up MCP config for Claude Code
tessl init --agent cursor         # sets up for Cursor
tessl init --agent codex          # etc.
# Supported: claude-code, cursor, gemini, codex, openhands, openclaw,
#            copilot, copilot-vscode, agents, tessl-agent

tessl mcp proxy <workspace/mcp> — proxies calls to a workspace-registered MCP server through the Tessl gateway. Use when an upstream MCP server requires OAuth and CI can't complete the flow.

Authentication

tessl whoami          # check login + workspace name
tessl login           # browser OAuth
tessl logout
tessl org list        # list orgs you belong to
tessl workspace list  # list workspaces you're a member of

# For CI / non-interactive: set TESSL_TOKEN env var

Setup / Init

tessl init                          # set up tessl.json + MCP config interactively
tessl init --agent claude-code      # configure MCP for a specific agent
tessl init --agent cursor --agent claude-code   # multiple agents
tessl init --name my-project        # set project name in tessl.json

Project Management

Evals and other repository-connected data need a linked Tessl project.

tessl project create my-project --workspace myworkspace  # create + link
tessl project link --workspace myworkspace               # link to existing project
tessl project repair                                     # fix broken tessl.json link
tessl project repair --json                              # machine-readable output

Install / Update / Uninstall

# Install
tessl install workspace/plugin-name
tessl install workspace/plugin-name@1.0.0       # pin version
tessl install --global workspace/plugin-name     # to ~/.tessl/
tessl install github:user/repo
tessl install github:user/repo --skill skill-one --skill skill-two
tessl install file:./local-plugin                # from local path
tessl install --yes workspace/plugin-name        # skip prompts
tessl install --accept-warnings workspace/plugin  # skip security policy prompts

# List, check, update
tessl list                           # list installed plugins
tessl list --global                  # global installs
tessl outdated                       # check for newer versions
tessl update workspace/plugin-name   # update one
tessl update --yes                   # update all without prompts
tessl update --force workspace/plugin # include breaking updates

# Uninstall
tessl uninstall workspace/plugin-name
tessl uninstall workspace/plugin-name --skill skill-name  # one skill only
tessl uninstall --global workspace/plugin-name

Diagnostics

tessl doctor             # auth + manifest diagnostics
tessl doctor --json
tessl cli update         # update CLI to latest
tessl cli update --channel beta
tessl config get         # show all config
tessl config set shareUsageData false

Common Failures (consumer)

ErrorCauseFix
Not authenticatedSession expiredRun tessl login or set TESSL_TOKEN
tessl.json missing / project not foundEvals need a linked projectRun tessl project create or tessl project repair
Skill not triggering after installDescription not specific enoughRewrite description as explicit trigger conditions with example phrases
MCP search/install not workingNot authenticated in MCP sessionUse the login MCP tool first

skills

tessl-basics

SKILL.md

tile.json