tile-creator

name: tile-creator description: Create tessl tiles containing docs, rules, or skills. Use when a user wants to create a tile, package content for tessl, or needs help with tile.json configuration. Also triggers on "create tile from", "convert to tile", "turn into tile", "make tile from", or "tile this repo" for existing content.

Tessl Tile Creator

Create tessl tiles from scratch or from existing content (repos, docs, packages).

Choosing Content Types

Decision checklist

1. Does it describe steps to do something? (deploy, migrate, build, test, release) → Skill. Workflows, runbooks, and step-by-step procedures are skills, even if the source calls them "documentation."
2. Is it a constraint that must ALWAYS be enforced? (MUST, NEVER, always) → Rule (use sparingly)
3. Is it factual reference material? (APIs, schemas, config, architecture) → Docs

Common mistake: Putting procedural/workflow content into docs. If the content has numbered steps, imperative verbs, or describes a process — it belongs in a skill, not docs.

Most content should be docs or skills. Rules are reserved for critical behavioral constraints only.

Creating the Tile Structure

Two methods are available. Use whichever is available in your environment:

Option A: MCP tool (preferred if available)

Use the mcp__tessl__new_tile tool. It has typed parameters so there's no syntax to get wrong, and it never triggers interactive prompts.

Parameters:

• name: "workspace/tile-name" (required)
• summary: brief description (required)
• path: absolute output directory path
• docs: true for documentation tiles
• rules: rule name for rules tiles
• skill: {"name": "skill-name", "description": "..."} for skill tiles
• describes: purl string for package docs
• isPrivate: boolean, defaults to true. Ask the user whether this tile should be public or private — the default is private, meaning only workspace members can discover and install it.

Option B: CLI

Use the tessl tile new command with ALL required flags:

tessl tile new \
  --name workspace/tile-name \
  --summary "Description" \
  --workspace workspace \
  --path /absolute/path/to/tile \
  --docs  # or --rules rule-name, or --skill-name name --skill-description "desc"

Critical: Always pass --workspace — omitting it triggers an interactive prompt that blocks execution. The --workspace value must match the prefix of --name (e.g., if --name local/foo, then --workspace local).

Visibility: Tiles are private by default. Ask the user whether the tile should be publicly discoverable or restricted to their workspace. To make it public, add --public to the CLI command or set "private": false in tile.json. This is a manual setting — it is not gated by quality score or any validation process.

See CLI commands for full flag reference.

Path rule: Always use absolute paths for tile creation and ALL subsequent file operations. Store the tile's absolute path and use it consistently — the working directory can change between tool calls.

After scaffolding, validate with: tessl tile lint /absolute/path/to/tile

After Lint Passes

Always suggest these next steps to the user:

• Skill review (only if the tile has skills): tessl skill review <path-to-skill> — scores description and content quality with actionable suggestions. Iterate until satisfactory.
• Evals (always, for every tile): tessl scenario generate <tile-path> — generates eval scenarios. Once complete, download with tessl scenario download <id>, review for correctness, then run with tessl eval run <tile-path>.

Workflows

Choose the most relevant workflow based on your task:

• From scratch (no existing content): tile-from-scratch.md
• From existing source code (repo, package, codebase): tile-from-source.md
• From existing docs/context (markdown, .mdc files, other tiles): tile-from-docs.md

All workflows use the scaffolding method described above (MCP tool or CLI).

Package Documentation

When documenting software packages, use the { .api } marker for API signatures.

API Marker Format

Mark all public API elements:

### createClient(options) { .api }

Creates a new client instance.

**Parameters:**

- `options.apiKey` (string) - API key for authentication
- `options.timeout` (number, optional) - Request timeout in ms

**Returns:** `Client` - The client instance

tile.json for Packages

Include the describes field with a purl:

{
  "name": "tessl/npm-example",
  "version": "2.0.0",
  "summary": "TypeScript SDK for Example API",
  "private": false,
  "docs": "docs/index.md",
  "describes": "pkg:npm/example-sdk@2.0.0"
}

Purl format: pkg:<ecosystem>/<name>@<version>

• npm: pkg:npm/openai@6.9.1
• pypi: pkg:pypi/requests@2.31.0 (normalize names: lowercase, hyphens)

References

• CLI commands for full tessl tile new usage
• docs format
• rules format
• skills format
• tile.json spec