Best Practice Scout

IMPORTANT: This skill is a mandatory pre-step. Run it BEFORE writing any implementation code. Do not skip it.

Search the Tessl registry for best-practice tiles and install them before starting work. This ensures the agent follows established conventions rather than relying on training data.

When to Activate

This skill MUST activate before starting any task that involves:

• Working with a framework or library (React, Next.js, Express, Tailwind, etc.)
• Writing or restructuring tests
• Setting up CI/CD pipelines
• Configuring authentication or authorization
• Error handling patterns
• API design or implementation
• Database migrations or schema design
• Docker or container configuration
• Linting, formatting, or code quality setup
• Security-sensitive code
• Any technology where "doing it wrong" is easy and costly

Do NOT activate for:

• Simple variable renames or typo fixes
• Reading or explaining existing code without changes
• Tasks where all relevant tiles are already installed and sufficient

Workflow

Step 1 — Check Existing Tiles

Read tessl.json and .tessl/RULES.md in the project root. List which tiles are already installed that relate to the current task.

If existing tiles fully cover the task's domain, state: "Already have best-practice guidance from [tile names]" and proceed with the original task.

Step 2 — Search for Relevant Tiles

Use the search MCP tool to find tiles related to the current task. Construct search queries from:

• The framework or library name (e.g. "react", "express", "zod")
• The task category (e.g. "testing", "error handling", "authentication")
• The specific pattern needed (e.g. "REST API design", "docker compose")

Run 1-3 searches with different query terms to maximize coverage. Prefer specific queries over broad ones.

Step 3 — Evaluate Results

For each tile found, assess:

1. Relevance — Does it cover the specific task at hand?
2. Overlap — Does an already-installed tile cover the same ground?
3. Quality signal — Does it come from a known workspace or have meaningful content?

If a found tile covers the same domain as an installed tile but appears more comprehensive or better maintained, flag it as a potential upgrade.

Discard tiles that are irrelevant or redundant.

Step 4 — Present Findings to User

Summarize what was found in a brief message:

Found [N] relevant best-practice tile(s) for [task description]:

- **workspace/tile-name** — [one-line summary of what it covers]
- **workspace/tile-name** — [one-line summary]

[If upgrade candidate]: Note: **workspace/new-tile** may be a better alternative to the already-installed **workspace/old-tile** — [reason].

Install these before proceeding? (y/n)

If nothing relevant was found, state: "No relevant best-practice tiles found in the registry" and proceed with the original task.

Step 5 — Install on Approval

On user approval, use the install MCP tool to install the selected tile(s).

After installation, briefly summarize the key practices the tile introduces (2-3 bullet points max) and then proceed with the original task, following the newly installed guidance.

Step 6 — Handle "Don't Ask Again"

If the user says they don't want to be asked about tile installation in future (e.g. "just install them", "stop asking", "auto-install from now on"), respect this for the remainder of the session. In subsequent activations during the same session, install relevant tiles without prompting and just summarize what was installed.

Error Handling

• If search returns no results or fails: proceed with the original task using existing knowledge. Do not block the user's work.
• If install fails: report the error, note the tile name for manual installation, and proceed with the original task.
• If the user declines installation: proceed immediately with the original task. Do not re-suggest the same tile in the same session.

Rules

1. ALWAYS run this skill before writing implementation code. Do not start coding until the search is complete.
2. The search should be fast — 1-3 queries max. Do not over-research.
3. Never install tiles without user consent (unless the user has opted into auto-install).
4. Always check existing tiles first to avoid suggesting duplicates.
5. Prefer specific search terms over generic ones.
6. Keep summaries brief — the user wants to get to work, not read a report.
7. If in doubt about whether to activate, ALWAYS activate. A quick search that finds nothing costs seconds. Skipping it and writing bad code costs hours.