Tessl Product Context for Action Generation

This reference helps the action generator recommend the right type of fix — especially when to suggest creating, updating, or removing a Tessl plugin vs simpler alternatives like editing AGENTS.md or adding a one-line rule.

What Is Tessl?

Tessl is an agent context management platform. It helps AI coding agents use open-source dependencies and internal tools correctly by providing structured, versioned knowledge packages called plugins (previously referred to as tiles).

What Is a Plugin?

A plugin is a versioned package of agent context. It can contain:

• Skills: Reusable workflows and multi-step procedures (SKILL.md files)
• Rules: Coding standards, conventions, and guardrails agents should follow
• Docs: Usage guides, API references, and examples
• Manifest: Metadata, version, and dependency information (tile.json)

Plugins are installed into a repository via tessl.json and the tessl install command. Once installed, their skills and rules are automatically available to coding agents (Cursor, Claude Code, etc.) working in that repository.

Plugins go through a lifecycle: create -> evaluate -> publish -> install -> update.

When to Recommend create_plugin

Recommend creating a new Tessl plugin when the finding points to a problem that is:

• Multi-faceted: The fix involves multiple skills, rules, or docs working together (e.g., "agents don't know how to use our internal auth library" needs a usage guide, API reference, and common-pattern skill)
• Structured knowledge about a domain: The fix packages expertise about a specific library, framework, or internal tool that agents need to learn
• Versioned and evolving: The context will need updates over time as the library or convention changes

Plugins can be published to the registry for use across repos, or kept as local/private plugins within a single repository. A repo-specific plugin is perfectly valid when the knowledge is structured enough to benefit from plugin packaging (multiple skills, rules, docs).

Examples of good create_plugin recommendations:

• "Create a plugin for the internal auth library with API docs, usage examples, and a skill for common auth flows"
• "Create a plugin packaging the deployment conventions so agents across all repos follow the same process"
• "Create a local plugin for the custom ORM wrapper with skills for common query patterns"

When to Recommend Simpler Alternatives

Not everything needs a plugin. Recommend simpler action types when:

• One-liner convention: A single rule like "always use bun not npm" -> add_rule to AGENTS.md or .cursor/rules
• Quick note or single paragraph: A short piece of context that doesn't warrant its own plugin -> create_context (add to AGENTS.md)
• Trivial config: A quick setting change -> configure_tools
• Code fix: The problem is in the code itself, not missing context -> update_code or refactor

Rule of thumb: if the fix is a single sentence or paragraph, it's probably a rule or context update. If it's a body of structured knowledge with skills, it's a plugin.

When to Recommend update_plugin

Recommend updating an existing plugin when:

• A plugin's content needs changing — its skills, rules, or docs are incomplete, incorrect, or missing coverage for the area the finding describes
• A plugin is installed but its version is outdated and a newer version addresses the finding
• A plugin's configuration needs adjusting (e.g., enabling a disabled skill or rule)

When to Recommend remove_plugin

Recommend removing a plugin when:

• A plugin is actively causing harm (its rules conflict with the codebase's actual conventions)
• A plugin is redundant (its content duplicates what's already in AGENTS.md or other context files)
• A plugin is stale and unmaintained, providing outdated guidance

For the full list of action types and their definitions, see the Action Types table in findings-schema.md.