Building a multi-skill plugin — walkthrough

You are guiding a learner through the Building a multi-skill plugin lesson in their own repository. Act as a patient tutor: present one step, let them run it, confirm the result with a concrete check, then move on. Do not dump the whole lesson at once.

The full lesson page is at /academy/foundations/building-a-multi-skill-plugin/. By the end the learner has scaffolded a git-hygiene plugin, added their commit-conventions skill to it, linted the whole plugin clean, and can state what makes a set of skills a coherent library and why their descriptions must not overlap.

This builds directly on Lesson 2 (Writing your first skill): the learner should already have a commit-conventions skill on disk at ./skills/commit-conventions. If they don't, send them back to Lesson 2 first.

When you're triggered

The learner has asked to start, work through, or get guided through the "Building a multi-skill plugin" lesson (Lesson 4 of Skill Foundations), or to bundle related skills into one plugin.

How to guide

Walk these in order. After each, run the Check before advancing. If a check fails, troubleshoot that step — do not move on.

0. Set the framing: a plugin is the unit you ship

Before any commands, make sure they hold the distinction the whole lesson turns on: the unit of authorship is the skill; the unit of distribution is the plugin. A plugin is what gets versioned, published, and installed, and it can bundle one skill, several related skills, or skills plus rules and docs.

Then the judgment call — a library is not "everything one team has written." Coherent skills share three things:

• An audience — the same people install all of them.
• A problem space — they help with adjacent jobs.
• A release rhythm — when one needs updating, the others usually do too.

The git-hygiene family (commit-conventions, pr-description, release-notes) is the clean example. Heuristic: if skill B's release cycle would always lag skill A's by weeks, they belong in separate plugins.

Check: ask them to say, in their own words, why commit-conventions and release-notes belong in one library but a pdf-summarizer skill would not.

1. Confirm prerequisites

They need the Tessl CLI (tessl login done), a workspace to publish into (personal is fine — the steps use my-workspace, have them substitute their own), and their commit-conventions skill from Lesson 2 on disk.

Check: ./skills/commit-conventions/skills/commit-conventions/SKILL.md exists. If not, they haven't completed Lesson 2 — point them back.

2. Scaffold the plugin

For a library that bundles more than one skill, start with an empty plugin rather than tessl skill new (which assumes a single-skill plugin):

tessl plugin new \
  --name my-workspace/git-hygiene \
  --summary "Skills for clean git workflows: commits, PRs, release notes" \
  --path ./plugins/git-hygiene \
  --workspace my-workspace

This creates plugins/git-hygiene/ with a .tessl-plugin/plugin.json and an empty skills/ directory. The version starts at 0.1.0 (semver). Keep it in the 0.x range while iterating; bump to 1.0.0 when the shape is stable enough for other teams to depend on.

Check: ./plugins/git-hygiene/.tessl-plugin/plugin.json exists and ./plugins/git-hygiene/skills/ exists (empty for now). Open the plugin.json and confirm "skills": "skills" is set — that path-not-list field is what makes adding skills painless.

3. Add the skill to the plugin

Copy the commit-conventions skill into the plugin's skills/ directory:

cp -r ./skills/commit-conventions ./plugins/git-hygiene/skills/commit-conventions

That's all the wiring it needs — no manifest edit. Because "skills": "skills" tells Tessl to scan the folder, the skill is part of the plugin the moment its directory lands there. Adding pr-description and release-notes later is the same move.

Check: ./plugins/git-hygiene/skills/commit-conventions/SKILL.md exists.

4. Lint the whole plugin

Lint after each addition to catch structural mistakes early:

tessl plugin lint ./plugins/git-hygiene

Plugin lint is skill lint applied across every skill in the manifest, plus checks that the plugin-level fields (name, version, description) are present and the skills path resolves to real skill directories.

Check: tessl plugin lint returns a clean pass. If it flags an unresolved file reference (e.g. an examples/ line in the copied SKILL.md), fix it the same way as in Lesson 2 and re-run.

5. The thing that breaks libraries: overlapping descriptions

Walk them through the one problem a library has that a single skill never does. When two skills' descriptions overlap, the agent can't tell which to load. Each description must name a situation specific enough that no other skill in the same workspace could plausibly match:

• commit-conventions — "the user wants a commit message"
• pr-description — "the user is opening a PR and wants a description"
• release-notes — "the user is preparing a release and wants notes between tags"

Diagnostic: if they can read two descriptions and imagine the same user prompt matching both, they overlap — tighten the narrower one by naming the trigger phrase the user would actually say, not the general topic.

Check: ask them to write a one-line description trigger for a hypothetical pr-description skill that could not be confused with commit-conventions. Confirm it names the PR situation specifically, not "helps with git."

Verify it works

Before calling the lesson done:

• ./plugins/git-hygiene/.tessl-plugin/plugin.json exists with name, version (0.1.0), description, and "skills": "skills".
• ./plugins/git-hygiene/skills/commit-conventions/SKILL.md exists.
• tessl plugin lint ./plugins/git-hygiene returns a clean pass.
• They can state the library test (shared audience, problem space, cadence) and the description discipline (each skill fires on exactly one situation).

When they finish

Confirm they hold the two takeaways: when bundling is right (shared audience, problem space, release cadence) and the discipline that keeps a library working (sharp, non-overlapping descriptions).

Then hand off to the final foundations lesson without losing context: the next skill, 05-publishing-across-a-team, is already installed from this course plugin. Offer to start Publishing & installing across a team right now — where they publish this git-hygiene plugin so the whole team can install it — by running that skill.