Tenant skills user guide

Tenant skills let you teach Tealfabric how your organization works without changing application code. Each skill is a small package of written instructions and optional capability declarations. When the package is placed in your tenant workspace, Trace AI can load it on demand during chat.

What a skill is

A skill is not a separate application. It is a portable instruction set: a named folder that tells an agent what to prioritize, how to phrase work, and which supporting actions it may request. Skills are meant for durable knowledge, such as how to triage support tickets, how to summarize documents in your house style, or which escalation rules apply in your region.

Skills complement one-off chat messages because the guidance can be loaded again in later turns until context limits trim older tool results.

Where skills live

Create a top-level folder named SKILLS in your tenant workspace file storage. Inside it, add one subfolder per skill. The folder name is the skill id Trace AI passes to load_tenant_skill: letters, numbers, underscores, and hyphens only, up to 64 characters.

Each skill folder must contain a file named SKILL.md. That file holds the instructions the agent should follow. You may also add skill.json, which describes the skill in a structured form and lists optional capabilities.

If you manage tenant files through Workspace → Documents, create the SKILLS path there. If your operations team deploys tenant files through a release process, include the SKILLS tree in that deployment.

When you add, change, or remove a skill folder, Trace AI discovers valid packages on the next chat run that builds MCP context. Malformed folders are skipped so one broken package does not block the rest.

Enabling skills in your environment

Use Trace AI in chat or POST /api/v1/chat/trace-ai from automation. Other agents (for example Platform Engineer Agent) do not expose load_tenant_skill. If skills do not appear or never load, ask your platform operator whether Trace AI and tenant skills are enabled for your deployment.

See Trace AI Agent for endpoints, access, and examples.

The SKILL.md file

Write SKILL.md in plain Markdown. Start with a clear title using a level-one heading (#), because that title becomes the default description when you omit one in skill.json. The body should read like guidance to a capable colleague: scope, steps, tone, what to avoid, and when to ask for clarification.

Keep instructions specific enough to change behavior but general enough to age well. Prefer “always cite the document path when recommending a file change” over “use tool X in step 3,” unless a named tool is already available in your tenant MCP catalog. Long skills are acceptable; the platform ingests the full file when the skill is loaded, subject to normal model context budgets on tool history.

The skill.json manifest (optional)

skill.json is optional. When present, it supplies metadata and capability hints. Tealfabric merges it with SKILL.md; if a field is missing in JSON, defaults are taken from the folder name and the first heading in the Markdown file.

A minimal manifest looks like this:

{
  "name": "invoice-review",
  "version": "1.0.0",
  "description": "Review incoming invoices against purchase-order rules.",
  "capabilities": {
    "prompt": ["Use the invoice checklist in SKILL.md", "Prefer tables for line-item comparisons"],
    "resources": ["my-invoice-hints"],
    "tools": ["search"]
  }
}

The name must match the safe identifier pattern and should match the folder name. The version must be three-part numeric form such as 1.0.0. The description should be one sentence an operator can recognize in logs or support notes.

Under capabilities:

How Trace AI uses skills

Trace AI does not copy all skills into the system prompt at the start of a conversation. When a task matches a skill, the model should call load_tenant_skill with skill_id set to your folder name. The platform returns the full SKILL.md body inside <Tenant_Skill id="..." version="...">...</Tenant_Skill>. That content stays in the conversation as a tool result until summarization or message budgets compress older tool history.

The list of skill ids available for your tenant appears in the load_tenant_skill tool description in the MCP tool catalog for that run.

Install one skill per concern when possible. Avoid contradictory rules across skills. Load when relevant; the agent is instructed not to reload the same skill on every message.

Authoring practices that work well

Name skills after the job they support, not after a person or a project codename. Version skill.json when you make material changes so operators can tell whether a deployment updated behavior. Test by asking Trace AI the same question before and after you add the folder, with realistic tenant file paths when the skill concerns documents.

Treat skills as production configuration. Use the same change control you would for guardrails or integration credentials.

Safety and boundaries

Skills cannot override MCP guardrails, API key scopes, or tenant isolation. They declare intent; the platform enforces what is actually allowed. If a skill lists a tool that your guardrails block, that tool remains unavailable.

For guardrail schema details, see MCP guardrails configuration schema.

Example: a document review skill

Create SKILLS/document-review/ with SKILL.md that defines sections (purpose, risks, recommended actions) and optional skill.json with "name": "document-review" and "version": "1.0.0". Open Trace AI and ask it to load document-review and summarize an attached file. Replies should follow the section order you defined.

Troubleshooting

See also

• Trace AI Agent
• AI, agents, and MCP introduction
• Platform Engineer Agent (MCP chat without on-demand skills)
• MCP guardrails configuration schema
• Data and Documents introduction