> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/creating-skills-and-plugins/create-a-plugin.md).

# Create a plugin

{% hint style="info" %}
**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`.
{% endhint %}

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](/creating-skills-and-plugins/publish-and-update.md).

{% hint style="info" %}
Your agent can decide the right shape and build it for you. Install Tessl's plugin creator with `tessl install tessl/plugin-creator`, or use Tessl Agent, which ships with it built in.
{% endhint %}

## 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:

```bash
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:

```json
{
  "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](/reference/configuration.md).

## 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](/creating-skills-and-plugins/create-a-skill.md). 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](/creating-skills-and-plugins/add-an-mcp-server.md).

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](/reference/configuration.md) for the detail.

## Validate

Lint checks the plugin structure and manifest:

```bash
tessl plugin lint ./api-conventions
```

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

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

## Next

* [Add an MCP server](/creating-skills-and-plugins/add-an-mcp-server.md) - give the plugin live tools or data.
* [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally.md) - install from your filesystem and iterate.
* [Publish and update](/creating-skills-and-plugins/publish-and-update.md) - share the plugin with your team or publicly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tessl.io/creating-skills-and-plugins/create-a-plugin.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.