Lessons

The lesson system provides contextual guidance and best practices that are automatically included in conversations when relevant. Lessons help users follow recommended patterns and avoid common pitfalls.

The lesson system is the core knowledge system in gptme. Skills are a special case of lessons that follow Anthropic’s folder-style format.

Overview

Lessons are markdown files with YAML frontmatter that specify when they should be included. The system automatically:

• Indexes lessons from configured directories

• Matches lessons based on keywords, patterns, and tools used

• Includes relevant lessons in conversation context

• Adapts inclusion behavior for interactive vs autonomous modes

Lessons vs Skills

The lesson system supports two formats:

Lessons (Core Format):

• Auto-loading: By keywords, patterns, and tools

• Frontmatter: match: {keywords: [...], tools: [...]}

• Best for: Context-aware guidance that appears automatically

• Example: “Git best practices” appears when discussing commits

Skills (Anthropic Format):

• Auto-loading: By name only (when skill name appears in message)

• Frontmatter: name:, description:

• Best for: Explicit knowledge bundles, portable across tools

• Example: “python-repl” skill loads when you mention “python repl”

Feature	Lessons (Core)	Skills (Anthropic)
Auto-loading	✅ Keywords, patterns, tools	⚠️ Name only (in message)
Frontmatter	match: {keywords: [...]}	name:, description:
Best for	Context-aware guidance	Explicit knowledge bundles
Bundled scripts	No	Yes (optional)

See Skills for details on the skills format.

How Lessons Work

When you start a conversation, gptme:

1. Scans configured lesson directories

2. Indexes lessons with their metadata

3. Monitors the conversation for keywords and tool usage

4. Automatically includes all matching lessons (no per-turn limit)

5. Applies a session-wide limit (default: 20) to prevent context bloat

When exiting, gptme displays a summary of lessons used in the session.

Lessons appear in the conversation context but are hidden by default in the interface. Use /log to see which lessons are included.

Lesson Format

Lessons use YAML frontmatter for metadata and Markdown for content:

---
match:
  keywords: [keyword1, keyword2, keyword3]
  tools: [tool1, tool2]
---

# Lesson Title

## Context
When this lesson applies...

## Pattern
Recommended approach:
```python
# Example code
```

## Outcome
What happens when you follow this pattern...

Metadata Fields

match (required)

Specifies when the lesson should be included:

• keywords: List of words/phrases that trigger inclusion

• tools: List of tool names that trigger inclusion

• At least one keyword or tool must be specified

Example:

---
match:
  keywords: [git, commit, branch]
  tools: [shell]
---

Creating Lessons

Basic Structure

Create a .md file in your lessons directory with:

1. YAML frontmatter with match criteria

2. Clear title

3. Context section (when to use)

4. Pattern section (what to do)

5. Outcome section (expected results)

Example lesson:

---
match:
  keywords: [commit message, git commit]
  tools: [shell]
---

# Git Commit Messages

## Context
When creating git commits in any repository.

## Pattern
Use Conventional Commits format:
```
type(scope): description

Optional body

Co-authored-by: Name <email>
```

## Outcome
Clear commit history, automated changelog generation.

Lesson Directories

Lessons are loaded from the following directories (if they exist):

User-level:

1. ~/.config/gptme/lessons/ - gptme native lessons

2. ~/.agents/lessons/ - Cross-platform standard

Workspace-level:

3. ./lessons/ - Project-specific lessons

4. ./.gptme/lessons/ - Hidden project-local lessons

Other:

5. ./.cursor/ - Cursor rules (auto-translated to keywords)

6. Directories configured in gptme.toml

7. Plugin lessons (auto-discovered from plugin paths)

The ~/.agents/ paths provide cross-platform compatibility with other AI tools.

Note

For skill directories (Anthropic SKILL.md format), see Skills.

Organize lessons by category:

lessons/
├── tools/           # Tool-specific guidance
├── workflows/       # Process and workflow lessons
├── patterns/        # General patterns
└── README.md        # Category overview

Best Practices

Keywords:

• Use specific, relevant terms

• Include variations (e.g., “commit”, “commits”, “committing”)

• 3-7 keywords per lesson is typical

Tools:

• Only list tools directly used in the lesson

• Use exact tool names (e.g., “shell”, “python”, “browser”)

Content:

• Keep lessons concise (< 100 lines preferred)

• Focus on one specific pattern or issue

• Include concrete examples

• Show both anti-patterns and solutions

Configuration

Environment Variables

Control lesson behavior with these variables:

# Enable/disable auto-include (default: true)
export GPTME_LESSONS_AUTO_INCLUDE=false

# Maximum lessons per session (default: 20)
# This is a session-wide limit - once reached, no more lessons are included
export GPTME_LESSONS_MAX_SESSION=20

# Refresh lessons each message (default: false)
export GPTME_LESSONS_REFRESH=true

Keyword Extraction

The system extracts keywords from both user and assistant messages to match relevant lessons. This unified approach ensures lessons are included based on all conversation context, providing guidance during both interactive and autonomous operation.

CLI Commands

Several commands help you work with lessons:

List Lessons

Show all available lessons:

/lesson list

Search Lessons

Find lessons matching a query:

/lesson search keyword

Show Lesson Content

Display a specific lesson:

/lesson show <lesson-id>

Refresh Lessons

Reload lessons from disk:

/lesson refresh

Example Lessons

The package includes example lessons in docs/lessons/:

Tools:

• shell.md - Shell command guidelines

• python.md - Python development patterns

• browser.md - Web browsing best practices

• patch.md - File editing patterns

Workflows:

• git.md - Git workflow and commit conventions

These serve as templates for creating your own lessons.

Migration Guide

Lessons Without Frontmatter

If you have existing lessons without YAML frontmatter:

1. They will still work (backward compatible)

2. They won’t be auto-included (no match criteria)

3. Add frontmatter to enable auto-inclusion:

---
match:
  keywords: [your, keywords, here]
---

# Existing Lesson Title
... existing content ...

Converting Lessons

To convert an existing lesson:

1. Add YAML frontmatter at the top

2. Identify relevant keywords from the content

3. List any tools the lesson references

4. Test matching with /lesson search

Before:

# Shell Best Practices

When using the shell tool...

After:

---
match:
  keywords: [shell, bash, command]
  tools: [shell]
---

# Shell Best Practices

When using the shell tool...

Troubleshooting

Lessons Not Appearing

If lessons aren’t being included:

1. Check indexing: Look for “Indexed n lessons” in logs

2. Verify keywords: Use /lesson search to test matching

3. Check limits: Ensure GPTME_LESSONS_MAX_SESSION isn’t too low (default: 20)

4. Verify format: Ensure YAML frontmatter is valid

5. Session limit: If resuming a conversation, the session limit may already be reached

Debug Lesson Matching

Use verbose logging:

gptme --verbose

This shows which lessons match and why.

See Also

• Skills - Skills format (Anthropic-style knowledge bundles)

• Tools - Available tools that lessons can reference

• Configuration - Configuration options

• Custom Tools - Creating custom tools with lessons

• Agents - Using lessons with AI agents