#Create a plugin

A single skill is already a minimal plugin. You create a plugin explicitly when you want to bundle more than one thing and version and share it as a unit: a set of related skills, a rule that captures a convention, a command the user invokes, an MCP server, or a hook. Keep a plugin focused on one responsibility; unrelated work belongs in separate plugins. Whatever it contains, Tessl installs it into each agent's native format, so one plugin serves your whole team across every agent Tessl supports.

This page covers scaffolding a plugin and choosing what each part should be. Adding an MCP server has its own page, and publishing is covered in Publish and update.

#Scaffold the plugin

tessl plugin new creates the plugin directory and its .tessl-plugin/plugin.json. Pass --skill or --rules to seed initial content, and set the workspace explicitly:

tessl plugin new --name engteam/api-conventions --summary "Conventions and workflows for our REST APIs" --workspace engteam --skill --skill-name write-endpoint --skill-description "When adding a REST endpoint" --path ./api-conventions

engteam is a stand-in workspace. Run tessl workspace list and use one of yours in its place.

#Anatomy of a plugin

A plugin is a directory with a manifest and one or more content types. The directory that contains .tessl-plugin/ is the plugin root:

api-conventions/
├── .tessl-plugin/
│   └── plugin.json
├── skills/
│   ├── write-endpoint/
│   │   └── SKILL.md
│   └── review-endpoint/
│       └── SKILL.md
├── rules/
│   └── api-style.md
├── commands/
│   └── new-migration.md
├── evals/
│   ├── scenario-0/
│   └── scenario-1/
├── .mcp.json
└── tessl.json

A plugin has one evals/ directory, at the plugin root, for all its skills. Do not put an evals/ directory under each skill. tessl.json links the directory to a Tessl project, which evaluations need. See Prove a skill works using evaluation.

The manifest declares what the plugin ships:

{
  "name": "engteam/api-conventions",
  "version": "0.1.0",
  "description": "Conventions and workflows for our REST APIs",
  "private": true,
  "skills": "./skills/",
  "rules": "./rules/",
  "commands": "./commands/",
  "mcpServers": ".mcp.json"
}

name, version, and description are required. skills and rules each take a path or an array of paths and default to their conventional directory (./skills/, ./rules/) when it exists; commands and mcpServers are declared explicitly. The full field reference, including author, homepage, repository, and license, is in Configuration files.

#Choose what each piece should be

Match the behavior you want to the right content type. Add only what earns its place.

• Skill - a workflow the agent reaches for when a task matches its description. Most content is skills. See Create a skill. To add a further skill to a plugin, author skills/<name>/SKILL.md directly.
• Rule - an always-on convention the agent follows without being asked. A plain Markdown file in rules/, no frontmatter. Use a rule when something should always hold ("errors return problem+json"), not just during one task.
• Command - a named action the user invokes on demand. A Markdown file in commands/. Use a command when the human wants a button to press rather than something the agent decides to do.
• MCP server - live tools or data, not just instructions. See Add an MCP server.

Hooks run a command automatically at an agent lifecycle event, such as after a tool runs or when a prompt is submitted. Declare them with a hooks (cross-agent) or nativeHooks (per-agent) field in .tessl-plugin/plugin.json; see Configuration files for the detail.

#Validate

Lint checks the plugin structure and manifest:

tessl plugin lint ./api-conventions

Confirm what will actually ship by packing it and inspecting the archive, not just linting:

tessl plugin pack ./api-conventions --output /tmp/check.tgz
tar tzf /tmp/check.tgz

#Next

• Add an MCP server - give the plugin live tools or data.
• Develop and test locally - install from your filesystem and iterate.
• Publish and update - share the plugin with your team or publicly.