Skills

A Skill is a reusable capability directory with a required SKILL.md and optional supporting files. Within Agent extensions, use a Skill to teach an Agent a workflow; use a Tool for an action, or an MCP connection for actions supplied by a remote server.

Ownership and content

Platform Skills are curated by Blazing Agents, visible to tenants, and read-only through /v1. Tenant Skills are uploaded by one tenant and can be selected by that tenant's Agents. A Skill's Attribution can filter tenant listings, but it is not an attachment permission or ACL.

Every ZIP must contain SKILL.md at its root. Its YAML frontmatter requires a lowercase kebab-case name and a non-empty description; an optional meta object and additional safe relative files can travel with it. The detail response lists the stored files.

Attachment and progressive loading

An Agent attaches Skills by ID in its skills array. A Turn initially receives only each selected Skill's name and description. When the request matches, the Agent calls activate_skill to load SKILL.md; files are not injected up front.

Selected platform Skill assets can be read through the constrained Skill path even when general file operations are off. Tenant Skill activation currently reads SKILL.md; its other uploaded files remain stored and listed but are not exposed to the runtime asset reader. General Sandbox files require the separate file_operation_sandbox group.

Create and attach a Skill

Install adm-zip in this Node backend, then create a minimal archive and attach the returned Skill ID while creating the Agent.

import { BlazingAgents } from "@blazing-agents/sdk";
import AdmZip from "adm-zip";

const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });
const skillMarkdown = `---
name: incident-summary
description: Summarize an incident into impact, cause, and follow-up actions.
---

# Incident summary

Use the three sections named in the description.`;

const zip = new AdmZip();
zip.addFile("SKILL.md", Buffer.from(skillMarkdown));
const skill = await client.skills.create({
  file: zip.toBuffer(),
  filename: "incident-summary.zip",
});
const agent = await client.agents.create({
  name: "Incident writer",
  skills: [skill.id],
});
console.log(agent.skills.includes(skill.id));

The Agent now receives the Skill's selection metadata and can activate its instructions when an incident-summary request matches the description.

Versions and lifecycle

Creating or updating a tenant Skill validates and uploads one complete immutable Storage version. An update keeps the Skill ID, atomically switches its active content version, and schedules the obsolete version for cleanup. Existing Agent attachments therefore use the updated content on subsequent Turn resolution without being reattached; a Turn already resolved keeps its selected version.

Platform Skills cannot be updated or deleted through the tenant API. A tenant Skill cannot be deleted while any Agent still references it: detach the ID from every Agent first. Deletion removes the product record and schedules its stored version for cleanup.

Production considerations

Validate archive layout and frontmatter before rollout. The service also rejects unsafe paths, invalid ZIPs, excess files, and size-limit violations.
Treat tenant Skill instructions as code-like input that can influence Agent behavior; review content and supporting files before attachment.
Roll out updates deliberately because every Agent attached by ID sees the new active version on its next resolved Turn.
Detach before deletion, and do not rely on obsolete Storage versions remaining available after cleanup.
Never put API keys, provider credentials, or other secrets in Skill content.

Create and attach a Skill

Reference

TypeScript SDK: Skills and Agent configuration
REST API: Skills and Agent configuration

On this page