Writing your first skill — walkthrough

You are guiding a learner through the Writing your first skill lesson in their own repository. Act as a patient tutor: present one step, let them do it, confirm the result with a concrete check, then move on. Do not dump the whole lesson at once, and do not write the SKILL.md for them — the point is that they author it and understand why each line is there.

The full lesson page is at /academy/foundations/writing-your-first-skill/. By the end the learner has scaffolded a commit-conventions skill, written its SKILL.md themselves, passed tessl skill lint, and installed it from their local filesystem so it fires on a real diff.

This walks them through authoring a commit-conventions skill. That is a different artifact from this walkthrough skill — never edit or overwrite this walkthrough; you are helping them build their own.

When you're triggered

The learner has asked to start, work through, or get guided through the "Writing your first skill" lesson (Lesson 2 of Skill Foundations), or to author their first skill.

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. Confirm prerequisites

Make sure they have: a coding agent (Claude Code, Cursor, Codex, or Gemini), the Tessl CLI (install per https://docs.tessl.io/introduction-to-tessl/installation, then tessl login), and a repo initialized with Tessl. If they need to set one up:

tessl init --agent claude-code   # or: --agent cursor

Check: tessl init has written a tessl.json in the repo. If tessl.json is missing, they have not initialized Tessl here yet. (Publishing to a shared workspace comes later, in Lesson 5; authoring and installing locally need none.)

1. Scaffold the skill

tessl skill new runs a wizard that creates a well-formed single-skill plugin in one shot:

tessl skill new \
  --name commit-conventions \
  --description "Use when the user asks for a commit message or wants help summarizing staged changes. Generates a Conventional Commits–formatted message from a diff." \
  --path ./skills/commit-conventions

This creates skills/commit-conventions/ (the plugin root) with a .tessl-plugin/plugin.json and a nested skills/commit-conventions/SKILL.md stub. The plugin.json points its skills path at that directory, and Tessl discovers the skill by convention — they never list skills by hand.

Check: the file ./skills/commit-conventions/skills/commit-conventions/SKILL.md exists, and ./skills/commit-conventions/.tessl-plugin/plugin.json exists. If not, re-read the tessl skill new output for the path it actually wrote to.

2. Write the SKILL.md

Have them open the stubbed SKILL.md and make it the real thing. Walk them through the two parts that decide whether the skill is any good, before they paste anything:

• The description is the whole trigger. It is the only thing the agent reads when deciding whether to load the skill. Write it as a trigger condition (what the user is doing) plus a capability statement (what the skill produces). "Helps with git" is too vague to ever fire; name the user-visible situation, then the artifact.
• The body briefs the agent, not the user. Numbered steps for sequential actions, a decision table for the Conventional Commits type classification, a tight constraint list for the subject-line rules. Leave out anything the description already said or that the agent can read directly from the diff.

A complete, lint-clean target looks like this — have them read each section before pasting, and ask them why each line earns its place:

---
name: commit-conventions
description: Use when the user asks for a commit message or wants help summarizing staged changes. Generates a Conventional Commits–formatted message from a diff.
---

# Commit Conventions

You help the user write commit messages that follow the Conventional Commits specification.

## When you're triggered

The user has staged changes and wants a commit message, or has asked for help summarizing recent changes.

## What to do

1. Read the staged diff (`git diff --cached`) if you haven't already.
2. Identify the dominant change type. Use the table below.
3. Compose a message of the form `<type>(<optional scope>): <imperative subject>`.
4. Add a short body only if the diff has consequences a future reader would want flagged — breaking changes, migrations, security fixes.
5. Show the user the message before they commit. Don't run `git commit` unless they ask.

## Type table

| Type | When |
|---|---|
| `feat` | New user-visible capability. |
| `fix` | Bug fix the user can perceive. |
| `refactor` | Internal restructure with no behavior change. |
| `docs` | Documentation only. |
| `test` | Tests only. |
| `chore` | Tooling, deps, build, CI — anything below the user's perception. |
| `perf` | Measurable performance improvement. |

## Subject line rules

- Imperative mood ("add", not "added" or "adds").
- Lowercase first letter, no trailing period.
- Hard limit 72 characters.
- Scope is optional but useful when the repo has clear surfaces: `feat(auth):`, `fix(api):`.

## Examples

See `examples/` for diff → message pairs you can use to ground your reasoning.

Check: the SKILL.md has frontmatter with name and a specific description, and a body with numbered steps, the type table, and the subject-line rules. Ask them to point at the description and say in their own words what it controls.

3. Lint it

Validate structure against the Agent Skills specification before installing:

tessl skill lint ./skills/commit-conventions

This checks the plugin root has a valid .tessl-plugin/plugin.json, the required SKILL.md frontmatter fields are present, every file referenced from SKILL.md exists, and the directory matches the spec. Lint checks structure, not quality — a clean pass doesn't mean the description is sharp enough to fire (that's tessl review run, a later lesson).

Check: tessl skill lint returns a clean pass. If it flags the examples/ reference and there is no examples/ folder, either add one or remove that line from SKILL.md, then re-run.

4. Install it from your filesystem

They don't have to publish to try it — install straight from the local path:

tessl install file:./skills/commit-conventions

This is the authoring loop: edit SKILL.md, reinstall, try it, edit again. To skip the manual reinstall, run tessl install --watch-local on its own (no source) — it watches every local file-source skill already installed and re-syncs on each save:

tessl install --watch-local

Check: tessl list shows their commit-conventions plugin installed with a version and a Synced status. If not, re-run and read the error, usually a missing tessl login or no tessl.json.

5. Trigger it on a real diff

Stage a real change, then ask the agent for a commit message:

echo "# Try Skills" > README.md
git add README.md

Then, in the agent chat:

"What's a good commit message for the staged changes?"

The agent should match the prompt to the skill's description, read the staged diff, and propose something like:

docs: add initial README

Adds a placeholder README to seed the repo.

Have them stage different changes (a new function, a bug fix, a dependency bump) and watch the prefix change: feat:, fix:, chore:, refactor:.

Check: the agent produced a Conventional Commits message with a sensible type prefix for the staged diff. The course bundles its own commit-conventions demo skill (from Lesson 1), so if the trigger is ambiguous, have them rely on the one they just authored and installed from file: — or uninstall the course's copy for the duration of this step.

Verify it works

Run all four before calling the lesson done:

• tessl skill lint ./skills/commit-conventions returns a clean pass.
• tessl list shows their commit-conventions plugin installed.
• A prompt like "What's a good commit message for the staged changes?" triggers their skill.
• An unrelated prompt, like "explain this function", does not load the skill. Skills load on intent, not always-on.

If it doesn't trigger and no older skill is shadowing it, the usual cause is a too-narrow description; make sure the words a user would actually say ("commit", "message", "staged") appear in the description field.

When they finish

Confirm they can state the instinct the lesson builds: a sharp description so the agent knows when to reach for the skill, and a tight body that tells it how without crowding the context window.

Then hand off to the next lesson without losing context: the next skill, 03-skills-vs-mcp-and-context-files, is already installed from this course plugin. Offer to start Skills vs MCP, and context files right now — where they learn when a skill is the right tool versus a context file or an MCP server — by running that skill.