Skill package reference

A skill package contains a SKILL.md entry point and optional supporting files. The Portal stores each published package as a revision.

Package formats

An archive has exactly one case-sensitive SKILL.md at its root or inside one enclosing directory. Every package file belongs under that root. Supporting file paths are relative to the entry point.

ZIP archives use stored or deflate compression. Links, special files, unsafe paths, and duplicate normalized paths are invalid.

This example has one entry point and one supporting file:

release-summary/
	SKILL.md
	references/
		style.md

The structure is illustrative. The skill name comes from SKILL.md, not the directory name.

SKILL.md

SKILL.md is UTF-8 text. It begins with YAML frontmatter between --- lines. Its Markdown body contains the instructions.

---
name: release-summary
description: Write release notes from a supplied list of changes.
disable-model-invocation: true
---

## Write the summary

Use only the changes the user supplies.
Group the changes under Added, Changed, and Fixed.
Omit empty groups.
Do not invent version numbers, release dates, or resolved defects.

Required fields

Names contain 1 to 64 lowercase letters, digits, or single hyphens. Names cannot begin or end with a hyphen. A creator cannot reuse a name within the same organization. Different creators can use the same name.

Optional fields

Other frontmatter keys remain package metadata. They do not configure a model, provision tools, or execute code.

Frontmatter contains string keys and JSON-compatible values. Duplicate keys, YAML aliases, and null characters are invalid.

Supporting files

Supporting files can contain reference text, templates, scripts, or binary data. A file belongs to the same revision as SKILL.md.

Activation loads the instructions. The assistant reads supporting text resources on demand instead of loading every file into the conversation.

A resource read requires an API-recognized text media type and valid UTF-8. It rejects control characters below U+0020 except tabs, carriage returns, and line feeds. Unknown file extensions receive application/octet-stream and are not readable by chat, even when the Portal can preview their text.

Files with .md or .txt extensions are suitable for supporting instructions and reference text.

Scripts are stored for inspection and download. BullSequana AI does not execute scripts from skill packages.

The Portal previews Markdown and shows other text as source. HTML and SVG remain source text. Binary files have a download action. Markdown image URLs appear as placeholders and do not load in skill previews.

Limits

The BSQAI API applies these default tenant limits:

Tenant configuration can change these limits. A resource read cannot exceed 64 KiB. Each unset limit uses its default.

The assistant's skill list can be smaller when the selected model has a limited context. Omitted skills remain available through explicit mentions.

The browser editor has separate limits:

Lower tenant limits also apply. Supporting text files above 2 MiB remain in the package but do not support direct text editing.

Paths use / separators. Absolute paths, empty segments, . segments, .. segments, backslashes, control characters, and drive prefixes are invalid in the editor.

Publication and access

Upload, save, and copy operations validate the whole package before publication. Failed validation does not publish a partial revision.

A new skill and a new copy are private to their creator and selected in Yours. A copy starts from the original's current revision and has independent revisions. Organization sharing gives other members read access. Editing, sharing, and deletion remain creator-only actions with the corresponding permissions.

Private skills remain creator-only. A platform administrator does not gain access to another member's private skill through administrator privileges.

Skills require a signed-in user session and these Skills permissions:

The management routes also require tenant-read access. API keys do not provide access to these routes; use a signed-in user session.

Supported chat surface

Skill activation is part of ordinary Portal text chat, with either a model or an Agent. It is not available in Deep Research, live Voicebot, or the OpenAI Responses and Anthropic-compatible endpoints. Storing a package through the management API does not add skill activation to those endpoints.

Conversation revisions

The activate_skill tool loads a selected skill's instructions. The read_skill_resource tool reads eligible supporting text in bounded chunks. Binary files and unrecognized media types are not readable through that tool.

The first activation pins a revision to the conversation. Later activations and supporting resource reads use that revision. Editing the skill does not replace the pinned revision.

Stop using keeps the transcript but excludes the skill's instructions from later model requests. An explicit mention resumes the same revision.

Unsharing or deletion blocks further activation and resource reads for members who lose access. Neither action retracts content already delivered to their conversations.

Validation errors

Related pages

• Use skills in chat
• Upload and manage skills