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
name:
tessl-authoring
description:
Use when creating or publishing Tessl plugins and skills — plugin new, skill new, plugin.json format, bundling MCP servers in a plugin, lint, publish, version bumps. Triggers on: "create a tessl plugin", "publish this skill", "push to the registry", "bump the version", "lint the skill", "make a plugin", "share a skill", "tessl skill new".

Tessl Authoring

Everything about creating and publishing plugins and skills to the Tessl registry.

Create a Plugin

tessl plugin new \
  --name workspace/plugin-name \
  --summary "One-line description" \
  --workspace workspace \
  --skill \
  --skill-name skill-name \
  --skill-description "Trigger description"
# --path ~/work/my-plugin   (optional)
# --public                  (default: private)
# --install                 (auto-install into current repo)

--skill or --rules is required — a plugin must have at least one component.

plugin.json format

{
  "name": "workspace/plugin-name",
  "version": "0.1.0",
  "description": "One-line description",
  "private": false
}

Fields:

  • name — must be workspace/plugin-name format
  • version — semver
  • description — one-line summary
  • private — defaults to true. Set to false to publish publicly.

Bundling MCP servers in a plugin

A plugin can bundle MCP server configuration via a .mcp.json file at the plugin root. When installed, Tessl writes the server config into each agent's native config file automatically (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, etc.). When updated, the config updates. When uninstalled, Tessl prunes it cleanly.

// .mcp.json at plugin root
{
  "mcpServers": {
    "my-internal-api": {
      "type": "stdio",
      "command": "node",
      "args": ["./scripts/my-mcp-server.js"]
    },
    "remote-service": {
      "type": "http",
      "url": "https://api.internal.example.com/mcp"
    }
  }
}

Skills, rules, and MCP servers are all first-class plugin content — same versioning, same install, same tessl update propagation across every harness.

Skill Lifecycle

# Create standalone
tessl skill new --name skill-name --workspace myws --description "Trigger description"
tessl skill new --install   # also install into current repo after creating

# Import (create plugin.json from an existing SKILL.md)
tessl skill import ./my-skill --workspace myws --public

# Lint
tessl skill lint              # current dir
tessl skill lint ./my-skill

# Publish standalone
tessl skill publish ./my-skill --workspace myws --bump patch --public

# Review quality (synchronous, local)
tessl skill review ./my-skill
tessl skill review --optimize ./my-skill          # auto-improve
tessl skill review --optimize --yes ./my-skill    # no confirmation
tessl skill review --threshold 80 ./my-skill      # fail if score < 80%

SKILL.md frontmatter

---
name: skill-name          # must match directory name
description: >-
  One or two sentences. Write as a TRIGGER CONDITION for an agent.
  Include explicit trigger phrases: "Triggers on: X, Y, Z."
---

name and description are the only required fields.

Lint

Always lint before publishing — the registry rejects malformed plugins.

tessl plugin lint                        # current directory
tessl plugin lint ~/work/my-plugin       # specific path
tessl skill lint                         # lint a skill in isolation

Publish

tessl plugin publish                              # current dir
tessl plugin publish ~/work/my-plugin             # specific path
tessl plugin publish ~/work/my-plugin --bump patch    # auto-bump if version exists
tessl plugin publish ~/work/my-plugin --bump minor
tessl plugin publish ~/work/my-plugin --bump major
tessl plugin publish ~/work/my-plugin --dry-run       # validate only
tessl plugin publish ~/work/my-plugin --verbose       # show every archived file
tessl plugin publish ~/work/my-plugin --version 1.2.0 # override version

Version rules: if version in plugin.json already exists in registry, publish fails unless you pass --bump. Set "private": false before publishing publicly. Moderation is async — may take a few minutes to appear.

Other Plugin Commands

tessl plugin info workspace/plugin-name           # show registry details
tessl plugin info workspace/plugin-name@1.0.0     # specific version
tessl plugin pack ~/work/my-plugin                # package to .tgz
tessl plugin migrate                               # migrate tile.json → plugin.json
tessl plugin unpublish --plugin workspace/plugin@0.1.2   # within 2 days only
tessl plugin archive --plugin workspace/plugin@0.1.2 --reason "reason"
tessl plugin archive --plugin workspace/plugin --reason "all versions"

Typical Workflows

Update and push an existing skill

# 1. Edit skills/<name>/SKILL.md in the plugin directory
# 2. If skill also lives at ~/.agents/skills/, sync it:
cp ~/.agents/skills/my-skill/SKILL.md ~/work/my-plugin/skills/my-skill/SKILL.md
# 3. Lint
tessl plugin lint ~/work/my-plugin
# 4. Publish with auto-bump
tessl plugin publish ~/work/my-plugin --bump patch

Create a new plugin from scratch

tessl plugin new --name myws/my-plugin --workspace myws \
  --skill --skill-name my-skill \
  --skill-description "Trigger description for the skill" \
  --path ~/work/my-plugin
# Edit the generated SKILL.md
tessl plugin lint ~/work/my-plugin
tessl plugin publish ~/work/my-plugin

Tessl Review (async, server-side)

Distinct from tessl skill review above (synchronous, local). Runs server-side, supports CI gating, custom rubrics, and automated fix loops.

# Quality review
tessl review run ./my-skill --workspace engteam
tessl review run ./my-skill --workspace engteam --threshold 80 --json   # CI gate
tessl review run ./my-skill --workspace engteam --label "after refactor"
tessl review run ./my-skill --workspace engteam --force   # skip cache

# Security scan (Snyk-powered)
tessl review run security ./my-skill --workspace engteam
tessl review run security ./my-skill --workspace engteam --fail-on high  # CI gate

# Auto-fix loop
tessl review fix ./my-skill --workspace engteam
tessl review fix ./my-skill --workspace engteam --threshold 90 --max-iterations 5 --yes

# View / manage
tessl review list --workspace engteam
tessl review view --last
tessl review view <run-id>
tessl review retry --last

Common Failures (authoring)

ErrorCauseFix
version already existsVersion in plugin.json already publishedAdd --bump patch
Workspace is requiredMissing --workspace on plugin newAdd --workspace yourworkspace
Must specify at least one of: --skill or --rulesPlugin needs at least one componentAdd --skill flag
Plugin structure is invalidMalformed plugin.json or SKILL.mdRun tessl plugin lint
Workspace not foundWrong workspace nameRun tessl workspace list
Moderation delayPlugin not yet searchable after publishWait a few minutes — moderation is async
Workspace
kumar
Visibility
Public
Created
Last updated
Publish Source
CLI
Badge
kumar/tessl-setup badge