Rapid Skill Loop

Goal

Turn a tiny capability idea into a Tessl-ready demo tile as quickly as possible.

The objective is not to produce a production-grade skill. The objective is to produce a convincing minimal skill that is easy to explain, easy to evaluate, and fast to show live.

Default Constraints

• Always ask which workspace to publish to before creating tile.json.
• Always publish demo tiles as private.
• Keep the skill narrow.
• Prefer one input and one output.
• Prefer one obvious output format.
• Generate exactly one eval scenario unless the user explicitly asks for more.
• Prefer publish flow over tessl eval run because publish uploads scenarios and starts evals more reliably.
• Optimize at most once in the normal demo path.
• Triple-check file format before announcing success.

Pick Good Demo Capabilities

Prefer tiny behaviors with obvious pass or fail behavior:

• messy text -> strict structure
• classify input into a small fixed set
• rewrite input into a short template
• extract a few fields without inventing details

Good examples:

• turn rough meeting notes into a 4-bullet recap
• normalize a bug report into a fixed brief
• classify support tickets into severity + owner
• turn a release note blob into a short announcement

Avoid:

• broad research skills
• multi-step autonomous workflows
• anything requiring many tools
• anything where "good output" is mostly subjective

Workflow

1. Freeze The Scope

Turn the user's idea into one sentence:

• input: what comes in
• output: what must come out
• rule: what must not be invented

If the user gives a broad idea, shrink it immediately.

Before creating files, ask:

• what workspace should this publish to?

If the user does not care, ask once anyway. The tile name must be workspace/tile.

2. Create The Minimal Tile

Create:

• tile.json
• skills/<skill-name>/SKILL.md

Keep the first version short and concrete.

The skill should usually include:

• what it does
• when to use it
• exact output shape
• one or two hard rules

Use these exact format rules:

• tile.json must use "name": "workspace/tile-name"
• tile.json must include "private": true
• SKILL.md must start with YAML frontmatter
• frontmatter must include name and description
• the body should stay short and concrete

Use this tile.json shape:

{
  "name": "WORKSPACE/TILE_NAME",
  "version": "0.1.0",
  "summary": "One-sentence summary of the tiny skill.",
  "private": true,
  "skills": {
    "TILE_NAME": {
      "path": "skills/TILE_NAME/SKILL.md"
    }
  }
}

Use this SKILL.md shape:

---
name: TILE_NAME
description: Use when INPUT needs to become OUTPUT. Include the exact output shape and one or two trigger phrases.
---

# Skill Name

## Exact Output Format

```md
<exact output format here>

Rules

• Do not invent missing details.
• Keep the output short and structured.

Completion Checklist

• output follows the exact format
• required fields are present
• no invented details

### 3. Create One Eval Scenario

Create exactly one scenario under:

- `evals/scenario-1/task.md`
- `evals/scenario-1/criteria.json`

Prefer a scenario that checks:

- output structure
- inclusion of required fields
- no invented details

Use a simple weighted checklist.

The scenario format must be strict.

`task.md` should:

- describe the task briefly
- specify the output file name
- include the input inline in a `FILE:` block

Use this `task.md` shape:

```md
# Scenario 1

## Problem Description

Transform the provided input into the required output format.

## Output Specification

Save your output to `output.md`.

## Input Files

=============== FILE: inputs/source.txt ===============
<input goes here>

criteria.json must use Tessl's weighted checklist shape:

{
  "context": "Evaluate whether the output follows the requested format and avoids invented details.",
  "type": "weighted_checklist",
  "checklist": [
    {
      "name": "required_heading",
      "description": "Output contains the required heading.",
      "max_score": 40
    },
    {
      "name": "required_fields",
      "description": "Output includes the required fields or bullets.",
      "max_score": 40
    },
    {
      "name": "no_invented_details",
      "description": "Output does not introduce facts not present in the input.",
      "max_score": 20
    }
  ]
}

Do not use:

• id
• weight
• top-level criteria

Use:

• top-level context
• top-level type
• top-level checklist
• item name
• item description
• item max_score

4. Run Review

Run:

tessl skill review <tile-dir>/skills/<skill-name>

If the review points to obvious vagueness, missing output contract, or weak constraints, tighten the skill.

5. Optimize Once

If the user wants the full loop, run:

tessl skill review --optimize --yes <tile-dir>/skills/<skill-name>

Inspect the diff before accepting it as a demo artifact. Prefer changes that make the workflow more concrete or the output format more explicit.

6. Validate Before Publish

Before publishing, verify:

tessl tile lint <tile-dir>
find <tile-dir>/evals -maxdepth 2 -type f | sort
cat <tile-dir>/tile.json

Confirm that:

• the tile name includes the workspace
• private is set to true
• SKILL.md has frontmatter
• there is exactly one scenario
• criteria.json uses weighted_checklist

7. Publish To Trigger Evals

Prefer this path:

tessl tile publish <tile-dir>

If the version already exists:

tessl tile publish <tile-dir> --bump patch

This is the default demo path because publish uploads the eval scenarios and starts the eval run.

Never publish a public tile for this workflow. If tile.json does not contain "private": true, fix it before publishing.

Only use tessl eval run if the user explicitly asks for local-only testing and the CLI path is known to work.

Writing Rules

• Prefer short headings and short bullets.
• Make the output contract explicit.
• Do not add domain lore unless the task requires it.
• Do not generate multiple scenarios by default.
• Do not optimize for completeness; optimize for demo speed and legibility.
• Do not improvise JSON shapes.
• Do not omit frontmatter.
• Do not use a bare tile name without workspace/.
• Do not publish public.

Suggested Output Pattern For The Generated Skill

When possible, steer the generated skill toward this shape:

1. Goal
2. Exact output format
3. Rules
4. Completion checklist

Demo Script Shape

When asked to drive the full demo, follow this sequence:

1. ask which workspace to publish to
2. restate the tiny capability in one sentence
3. create the skill files
4. create one eval scenario
5. run review on skills/<skill-name>
6. optionally run optimize once
7. lint and check formats
8. publish to start evals
9. summarize what changed in one short paragraph

Completion Checklist

Before finishing, confirm that:

• the workspace is known
• the skill scope is tiny
• the output shape is obvious
• there is exactly one eval scenario unless the user asked for more
• review has been run on the skill directory
• tile.json uses workspace/tile
• tile.json sets "private": true
• criteria.json uses weighted_checklist
• publish has been run or is ready to run