Lesson 1 — Skills in 30 minutes

You've probably heard people talk about skills for coding agents. This lesson is the 30-minute version of finding out what they actually are: not by reading a definition, but by installing one, running it, and watching your agent behave differently because of it.

What you'll build

By the end you'll have:

• The bundled commit-conventions skill available in a repo of your choice (it ships with this course).
• A working understanding of where the skill lives on disk and how the agent finds it.
• Your first agent interaction that visibly uses the skill: a Conventional Commits message generated from a real diff.

What a skill actually is

A skill is three things stitched together:

1. A SKILL.md file, markdown with frontmatter. The frontmatter tells the agent when to load the skill (the description field). The body tells it how to do the job. This file is the contract.
2. Optional supporting files: examples, helper scripts, reference data. Anything the SKILL.md references.
3. A package wrapper, which in Tessl is a plugin. The plugin gives the skill a name (workspace/plugin-name), a version, and a place in the registry so anyone can install it.

That's it. There's no magic and no service running in the background. The agent reads SKILL.md when its description matches the work in front of it, follows the instructions, and produces output. Versioning, distribution, and quality signals sit around the skill, not inside it.

The mental model. Think of skills as the agent equivalent of small, well-tested libraries: each one does one thing, and your agent picks the right one for the job at hand.

Before you start

You need three things on your machine:

• A coding agent. The examples assume Claude Code or Cursor, but skills are agent-agnostic, so Codex and Gemini work too.
• The Tessl CLI. Follow the installation guide (Homebrew, winget, or the install script), then run tessl login.
• A repository to install into. Any git repo will do, and if you'd rather start clean, spin up an empty one so the exercises don't touch existing work:

mkdir try-skills && cd try-skills
git init

If you haven't initialized Tessl in this repo yet, do that now. It writes a tessl.json manifest, registers the Tessl MCP server, and writes the agent-specific rule files that point at your installs:

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

Step-by-step

1. Install the course

You install everything for this course in a single step. The plugin bundles the guided walkthroughs for every lesson and a ready-to-use commit-conventions skill: the one you'll watch work in a moment.

npx tessl install tessl-academy/skill-foundations

You'll see something like:

- Preparing installation...
- Installing 1 plugin...
✔ Installed tessl-academy/[email protected]

Two things just happened. Tessl downloaded the plugin into .tessl/plugins/tessl-academy/skill-foundations/ (the canonical, agent-agnostic location) and recorded it in your tessl.json so the dependency is tracked. The skill files live there, once, on disk. Your agent reaches them through the glue tessl init set up: agent-specific rule files that point back at that .tessl/ folder (CLAUDE.md plus .tessl/RULES.md for Claude Code, .cursor/rules/tessl__*.mdc for Cursor), backed by the Tessl MCP server it registered for search and pulling in context. One canonical install plus the per-agent glue Tessl generates for you is why the same plugin works across Claude Code, Cursor, and the rest without you converting anything. This one install is all you need for the whole course: each later lesson just has you run a different bundled skill.

2. Look at what landed

Open .tessl/plugins/tessl-academy/skill-foundations/. You'll find:

skill-foundations/
├── .tessl-plugin/
│   └── plugin.json                # versioned package metadata
└── skills/
    ├── commit-conventions/        # the skill you'll trigger in a moment
    │   ├── SKILL.md               # the contract: when to use, how to do it
    │   └── examples/
    │       ├── feat.diff
    │       ├── fix.diff
    │       └── chore.diff
    ├── 01-skills-in-30-minutes/   # the guided walkthrough for this lesson
    └── …                          # one walkthrough per lesson in the course

The skill this lesson is about is commit-conventions. Open its SKILL.md. Its frontmatter is the whole trigger mechanism:

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

That description is what the agent reads to decide whether to use this skill on any given turn. The body of the file tells it how. The body is short by design; SKILL.md should fit comfortably in your head.

The .tessl-plugin/plugin.json alongside it carries the package metadata and points Tessl at the skills it ships:

{
  "name": "tessl-academy/skill-foundations",
  "version": "0.1.0",
  "description": "Skill Foundations: a ready-to-use commit-conventions skill plus the guided walkthrough for each lesson in the course.",
  "skills": "skills"
}

The skills field is just a path: Tessl scans that directory for any subdirectory containing a SKILL.md, so one plugin can ship many skills without listing each one. That's exactly how this course fits in a single install: the commit-conventions skill and every lesson walkthrough sit side by side under skills/. Omit the field and it defaults to skills by convention.

3. Trigger the skill

Stage some real changes:

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

Then ask your agent, whether in Claude Code, Cursor's chat, or whatever you're using:

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

The agent recognizes that the prompt matches the skill's description, loads SKILL.md, reads your staged diff, and proposes something like:

docs: add initial README

Adds a placeholder README to seed the repo.

Try staging different changes (a new function, a bug fix, a dependency bump) and ask again. Watch the prefix change: feat:, fix:, chore:, refactor:. That's the skill doing its job.

Verify it's working

Three quick checks:

• tessl list shows tessl-academy/skill-foundations installed, with its version and a Synced status.
• The commit-conventions skill is on disk under .tessl/plugins/tessl-academy/skill-foundations/skills/commit-conventions/ and the plugin is recorded in tessl.json. Your agent reaches it through the rule files tessl init wrote (CLAUDE.md and .tessl/RULES.md, or .cursor/rules/tessl__*.mdc), which point at that .tessl/ folder — one canonical install, with the per-agent glue generated for you.
• A prompt that doesn't match the description, like "explain this function", does not load the skill. Skills load only when relevant; they're not always-on context.

If the skill doesn't trigger, the most common cause is a too-narrow prompt. The description field does fuzzy matching, not regex, so say the words "commit", "message", or "staged changes" and you'll hit it.

What you keep

You walk away with a real, installed commit-conventions skill in a repo of your choice, a clear picture of where it lives on disk, and a feel for the one thing that makes skills useful: the agent loads them on intent, does the job, and stays out of the way the rest of the time. That instinct, of something small and named that's summoned when relevant, is what every later lesson builds on.