Create a plugin

Bundle skills, rules, and commands into one versioned plugin, and choose what each piece should be.

Takeaway Reach for a plugin when a single skill is not enough: several related skills, an always-on rule, a command, or an MCP server that belong together. Scaffold it with tessl plugin new, add content under the plugin directory, and validate with tessl plugin lint.

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.

This is also available through your agent. Tessl's plugin creator will decide the right shape and build it for you: tessl install tessl/plugin-creator

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.

Flag	Purpose
--name	Plugin name, workspace/plugin format.
--summary	Short description of the plugin.
--workspace	Workspace for the plugin. Not inferred from --name, set it explicitly.
--path	Directory to create the plugin in.
--skill, --skill-name, --skill-description	Seed an initial skill.
--rules, --rule-description	Seed an initial rule file.
--install	Install into the current project immediately.
--public	Make it public. Private by default.

Anatomy of a plugin

A plugin is a directory with a manifest and one or more content types:

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

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.