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).