Migrate to Tessl

Purpose

Turn an existing Claude skill into a published Tessl tile. Target registry Quality 100% and with-context/Impact 100% when scenario rubrics are controllable.

Workflow

1. Preflight: run tessl --version and tessl whoami; stop if Tessl, login, source files, or required optimizer skills are unavailable.
2. Classify source: flat .md runs full migration; folder with SKILL.md preserves useful refs; existing tile starts at lint/Quality/evals; .skill archive gets unzipped first. Pick tile root by repo convention, not a fixed tessl/ folder.
3. Scaffold tile.json, root README.md, and skills/<skill-name>/SKILL.md.
4. Move executable guidance into SKILL.md; keep it lean enough for registry Quality review and move only optional depth elsewhere.
5. Normalize frontmatter, sync tile.json.summary, and write README sections: purpose, install, organization, output, eval status. Preserve safe custom fields as flat string metadata; omit local paths and source provenance.
6. Remove all source-provenance material: no personal/local source paths, no Migrated from, no Built from, no equivalent source sections.
7. Run lint, local skill review, tile validation, and dry-run publish. If lint fails, fix the named path or manifest field and rerun. If local review is below 100, patch the lowest-scored dimension before publishing.
8. Publish Quality or packaging changes with --skip-evals, wait for moderation, then inspect /skill-reviews; the exact version must be 3/3 on every dimension before eval work. If any dimension is below 3/3, patch only that dimension, bump the version, and repeat the --skip-evals gate.
9. Only after Quality is 100 on the exact content, publish with evals, wait for completion, and inspect misses with tessl eval view --json. If an eval misses, patch the skill or rubric, then repeat the Quality-only gate before the next eval-bearing publish.
10. Confirm tessl search --json <tile-name> reports aggregate, Quality, Impact, and eval average all 1, with scores.evals.count >= 3; report Security separately. In score triage, explicitly note when scores.quality, scores.impact, and scores.evals.average are already 1 before blaming eval count.

Required Shapes

SKILL.md frontmatter:

---
name: <skill-name>
description: Use when the user wants to <specific task and trigger terms>.
metadata:
  version: "0.1.0"
---

tile.json:

{
  "name": "<workspace>/<tile-name>",
  "version": "0.1.0",
  "summary": "<same trigger promise as the skill description>",
  "skills": [{ "path": "skills/<skill-name>/SKILL.md" }]
}

README must not contain source lineage. Use only user-facing sections such as what it does, when to use, install, organization, output format, and eval status.

Runbook defaults: private, 0.1.0, claude:claude-sonnet-4-6, --force after content changes, and --bump minor after Phase 7.

Command Anchors

Use these directly when the phase calls for them:

tessl --version
tessl whoami
tessl tile lint <tile-path>
tessl tile publish --dry-run <tile-path>
tessl tile info <workspace>/<tile-name>[@<version>]
tessl eval view <eval-run-id>
tessl search --json <tile-name>

Detailed References

Use only when the inline workflow is not enough:

• Prerequisites
• Preflight
• Scaffold
• Migrate Content
• Frontmatter And README
• Initial Publish
• Evals And Optimize
• Multi-Model Verify
• Lessons Learned

Done when

Published version has Passed Moderation ✔; /skill-reviews shows every Quality dimension at 3/3; tessl search --json reports aggregate, Quality, Impact, and eval average at 1 with at least 3 eval scenarios for total-score targets; Security is reported separately; local diff is committable.

Stop conditions

Stop and report when preflight fails, source parsing fails, Tessl project setup fails, scenario generation hangs >30 min on a second attempt, or three consecutive eval runs stay below 80% with-context. Otherwise keep each publish gated by its exact registry result.