@meistrari/tela-skills

Tela Skills Documentation

Complete reference for the @meistrari/tela-skills CLI, Skills, and Agents.

---

Table of Contents

• Overview
• CLI
• Skills
  • Canvas Management
  • Project Management
  • Prompt Listing
  • Test Cases
  • Task Management
  • Vault (File Management)
  • Common Utilities
• Agents
  • test-case-handler
  • file-explorer
• Architecture
• Key Patterns

---

Overview

@meistrari/tela-skills is a Claude Code skill package that connects Claude to the Tela platform. It enables AI-assisted prompt engineering, test case management, task validation workflows, and file operations through Tela's API.

Install:

bunx @meistrari/tela-skills

---

CLI

The CLI (cli.ts) is an interactive installer that sets up Tela Skills for Claude Code.

What it does

1. Environment selection — Choose between Production (api.tela.com), Staging (api.telastaging.com), or Localhost (Docker-based local development).
2. Skill installation — Copies skill source files from skill/ to ~/.claude/skills/tela/.
3. Agent deployment — Copies agent definitions from agents/ to ~/.claude/agents/ (if available).
4. Dependency installation — Installs @meistrari/vault-sdk into the skills directory via Bun.
5. Authentication — Browser auth for Production/Staging; Docker discovery + JWT generation for Localhost.
6. Session persistence — Saves credentials to ~/.tela/session.production, ~/.tela/session.staging, or ~/.tela/session.local and environment config to ~/.tela/environment and ~/.tela/.env.

Usage

# Install and configure (interactive)
bunx @meistrari/tela-skills

# Non-interactive localhost setup
bunx @meistrari/tela-skills --env localhost --repos-path /path/to/tela --workspace <slug-or-id> --yes

# Test locally during development
bun run cli.ts

# Verify skill loads correctly
bun --preload skill/preload.ts -e "console.log(Object.keys(tela))"

# Run commands against localhost
bun localhost.ts "console.log(await tela.listProjects())"

# List available localhost workspaces
bun list-workspaces.ts

File layout after installation

~/.claude/
  skills/tela/        # Skill source files + dependencies
  agents/             # Agent definitions (test-case-handler, file-explorer)

~/.tela/
  session.production  # API token (production)
  session.staging     # API token (staging)
  session.local       # JWT token (localhost, 30-day expiry)
  environment         # "production", "staging", or "localhost"
  .env                # TELA_API_URL, TELA_APP_URL
  tela-repo-path      # Path to tela monorepo (localhost only, for key discovery)

Localhost environment

For internal development against locally running Tela services:

1. Start Docker services in the tela monorepo (make dev)
2. Run bunx @meistrari/tela-skills and select "Localhost"
3. The CLI discovers Docker ports, reads AUTH_API_SECRET from packages/api/.env, loads auth settings from .repositories/auth-api/.env, fetches workspaces, and generates a JWT through the local auth-api JWKS signing flow

The localhost JWT has a 30-day expiry and is auto-regenerated when expired. Workspace selection is required during setup — use bun list-workspaces.ts to see available workspaces.

---

Skills

All skill functions are executed via bun --preload and accessed through the global tela object. The preload script (preload.ts) loads environment variables from ~/.tela/.env and exposes all exports as globalThis.tela.

Runtime pattern:

bun --preload ~/.claude/skills/tela/preload.ts -e "
  const result = await tela.someFunction(args);
  console.log(JSON.stringify(result, null, 2));
"

---

Canvas Management

File: skill/canvas.ts

Canvas is Tela's core concept — a versioned AI prompt with a message, variables, configuration, and optional structured output.

Types

Type	Description
Canvas	Top-level prompt object with metadata
CanvasVersion	Versioned snapshot: message, variables, config
Variable	Input/output definition (text, file, or mixed)
StructuredOutput	JSON schema for enforcing response format
CanvasMessage	Chat message (system, user, assistant, function)
CanvasVersionConfiguration	Model settings (model, temperature, type, functions)

Functions

createCanvas(payload) — Create a new canvas with an optional initial version.

tela.createCanvas({
  title: "My Prompt",
  projectId: "proj-uuid",
  version: {
    message: tela.createMessage("system", "You are a helpful assistant."),
    variables: [tela.createVariable("input", "text", { variableType: "input" })],
    configuration: { model: "gpt-5", temperature: 0 }
  }
})

getCanvas(canvasId) — Fetch a canvas and its latest version.

updateCanvas(canvasId, payload, options?) — Creates a new version. Pass { merge: true } to preserve existing fields like structuredOutput.

createCanvasVersion(canvasId, payload) — Explicitly create a new version for an existing canvas.

updateCanvasVersion(versionId, payload) — Modify an existing version by ID.

getCanvasVersion(versionId) — Fetch a specific version by ID.

Helpers

Function	Purpose
createMessage(role, content, index?)	Build a message with auto-generated HTML from markdown
createVariable(name, type, options?)	Define an input/output variable
createStructuredOutput(properties)	Build a JSON schema for validated responses
markdownToHtml(markdown)	Convert markdown to HTML, replacing {var} with <variable> tags

Defaults

• Model: gpt-5
• Temperature: 0
• Structured output: Use structuredOutput config — never embed schema in prompt text

---

Project Management

File: skill/projects.ts

Function	Description
listProjects(options?)	List projects (default limit: 10)
createProject(payload)	Create a new project with a title

tela.listProjects({ limit: 20 })
tela.createProject({ title: "New Project" })

---

Prompt Listing

File: skill/prompts.ts

List and retrieve canvas metadata without loading full version content.

Function	Description
listPrompts(options?)	List prompts with optional filtering
getPrompt(promptId)	Get a single prompt
getPromotedVersion(promptId)	Get the promoted (production) version

---

Test Cases

File: skill/test-cases.ts

Create, run, and manage evaluation datasets for canvas/prompt testing.

Statuses

initializing → ready → starting → running → finalizing → completed | failed | aborted | timeout | pending_review

Types

Type	Description
TestCase	Test definition: variables, files, messages, expected output
Generation	Execution result: content, status, feedback, validations

Functions

Function	Description
listTestCases(promptId, options)	List with pagination and filtering
getTestCase(testCaseId)	Get a single test case with its generations
createTestCase(payload)	Create one test case
createTestCases(payloads)	Batch create multiple test cases
updateTestCase(testCaseId, payload)	Update an existing test case
deleteTestCase(testCaseId)	Soft delete
runTestCase(testCaseId, versionId)	Execute against a specific canvas version
runTestCases(testCaseIds, versionId)	Batch execution
waitForTestCase(testCaseId, options)	Poll until completion (max 5 min default)
abortTestCase(testCaseId)	Stop a running execution

Helper

createTestCasePayload(promptId, variables, options) — Builds a properly formatted payload:

• Separates text variables from vault:// file references automatically
• Generates HTML for variablesRichContent
• Detects MIME types for file entries
• Constructs the files[] array

tela.createTestCasePayload("prompt-uuid", {
  document: "vault://file-uuid",
  question: "What is the main topic?"
}, {
  title: "Topic extraction test",
  expectedOutput: "Machine learning"
})

---

Task Management

File: skill/tasks.ts

Manage human-in-the-loop validation tasks generated from prompt executions.

Task Statuses

created → running → validating → completed | failed | cancelled

Functions

Function	Description
listTasks(options)	List with filtering by status, tags, date, creator, etc.
getTask(taskId, options?)	Get task details, optionally with analytics
updateTask(taskId, payload)	Update status, name, tags, or output content
approveTask(taskId)	Shorthand: set status to completed
deleteTask(taskId)	Soft delete one task
deleteTasks(taskIds)	Bulk soft delete
undoApprovalTasks(taskIds)	Revert completed tasks back to validating
getTaskVersions(taskId)	Get version/edit history
getTaskInsightsByVersion(versionId)	Approved/corrected/pending counts
getTaskMetrics()	Workspace-level metrics

---

Vault (File Management)

File: skill/vault.ts

Upload, download, and manage files using immutable vault:// references.

Function	Description
uploadFile(filePath, opts?)	Upload a local file, returns vault reference
uploadContent(name, content, opts?)	Upload string/Blob content
downloadFile(vaultRef)	Get file as Blob
downloadFileUrl(vaultRef)	Get pre-signed download URL
deleteFile(vaultRef)	Delete from vault
getFileMetadata(vaultRef)	File metadata
bulkUploadFiles(files)	Batch upload, returns array of references
uploadFileForVariable(filePath)	Upload specifically for test case variables
isVaultReference(value)	Check if a string is a vault:// reference
createPermalink(vaultRef, opts?)	Create a public shareable link
listPermalinks(vaultRef)	List all permalinks for a file
deletePermalink(vaultRef, id)	Delete a specific permalink

---

Common Utilities

File: skill/common.ts

Function	Description
loadApiKey()	Reads token from ~/.tela/session.production, ~/.tela/session.staging, or ~/.tela/session.local
getApiBaseUrl()	Returns API URL from globals or defaults
getAppBaseUrl()	Returns app URL for constructing viewer links
apiRequest<T>(method, path, body?)	Generic HTTP client with Bearer auth
parsePayload(payload)	Transforms vault:// references into {file_url} format
getProjectUrl(projectId)	Constructs viewer URL for a project
getCanvasUrl(canvasId)	Constructs viewer URL for a canvas

---

Agents

Agents are specialized sub-processes that Claude Code dispatches for complex, multi-step tasks. They run autonomously with their own context and tool access.

test-case-handler

Model: Opus (high capability)

Trigger: Use when the user wants to create, run, list, update, or delete test cases, or build evaluation datasets.

Capabilities:

• List test cases with pagination and filtering
• Batch create test cases from structured data
• Run tests against specific canvas versions and wait for results
• Handle file uploads to Vault before test case creation
• Automatically separate text vs. file variables
• Batch file operations for large datasets

Example prompts that activate this agent:

• "Create test cases for this canvas"
• "Run all test cases"
• "Build an evaluation dataset from these documents"

file-explorer

Model: Sonnet (balanced speed/capability)

Trigger: Use when files need to be analyzed before uploading to test cases or workstation tasks.

Capabilities:

• Find files by glob patterns
• Search file content with grep
• Read and categorize documents by topic or type
• Extract metadata and summaries
• Filter files by criteria (size, type, content)
• Prepare file lists for batch test case creation

Example prompts that activate this agent:

• "Find all markdown files about authentication"
• "Categorize these documents by topic"
• "Which PDFs in this folder are invoices?"

---

Architecture

Installation:
  bunx @meistrari/tela-skills
       │
       ▼
    cli.ts (interactive setup)
       │
       ├─→ ~/.claude/skills/tela/   (skill source + deps)
       ├─→ ~/.claude/agents/        (agent definitions)
       └─→ ~/.tela/                 (session, env config)

Runtime:
  bun --preload preload.ts -e "tela.someFunction()"
       │
       ▼
    preload.ts  →  loads ~/.tela/.env  →  sets global `tela`
       │
       ▼
    common.ts   →  auth (loadApiKey)  →  HTTP (apiRequest)
       │
       ├─→ canvas.ts      (create/update/get prompts + versions)
       ├─→ projects.ts    (workspace/project CRUD)
       ├─→ prompts.ts     (list/get prompt metadata)
       ├─→ test-cases.ts  (create/run/manage evaluations)
       ├─→ tasks.ts       (human-in-the-loop validation)
       ├─→ vault.ts       (file upload/download/manage)
       └─→ localhost-utils.ts (Docker discovery, JWT signing, workspace fetching)

---

Key Patterns

Dual content format

Every message and variable has both markdown and HTML representations. The markdown version uses {variableName} syntax; the HTML version uses <variable> tags.

Vault references

All files are referenced by immutable vault://UUID identifiers — never local paths. Upload files to Vault first, then use the returned reference in a canvas message, test cases, or task inputs.

Smart merging

updateCanvas() creates a new version rather than modifying existing ones. Pass { merge: true } to preserve nested config (like structuredOutput) while updating other fields.

Variable syntax

Reference variables as {variableName} (single braces) in markdown content. The markdownToHtml helper converts these to proper <variable> tags automatically.

Structured output

Define output schemas via the structuredOutput config on canvas versions. Never embed JSON schema instructions in the prompt text itself — use createStructuredOutput() instead.

Polling for completion

Long-running operations like test case execution use waitForTestCase() which polls at configurable intervals (default: 2s) up to a max timeout (default: 5 min).