# Skill package reference (/docs/reference/skill-packages) A skill package contains a `SKILL.md` entry point and optional supporting files. The Portal stores each published package as a revision. ## Package formats [#package-formats] | Upload format | Contents | | ------------- | ----------------------------------------------------------------------------------------------- | | `.md` | One Markdown file, stored as `SKILL.md`. The upload filename does not determine the skill name. | | `.zip` | A ZIP archive with `SKILL.md` and optional supporting files. | | `.skill` | A ZIP archive with the `.skill` extension. | 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: ```text release-summary/ SKILL.md references/ style.md ``` The structure is illustrative. The skill name comes from `SKILL.md`, not the directory name. ## SKILL.md [#skillmd] `SKILL.md` is UTF-8 text. It begins with YAML frontmatter between `---` lines. Its Markdown body contains the instructions. ```markdown --- 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 [#required-fields] | Field | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------- | | `name` | The skill name used by `/skill:`. | | `description` | A nonblank string of at most 1,024 characters. Chat uses the description to identify relevant skills. | 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 [#optional-fields] | Field | Portal behavior | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `disable-model-invocation` | Boolean. `true` requires an explicit mention. When absent or `false`, the assistant can load a relevant selected skill. | | `license` | Descriptive metadata shown in **Overview**. | | `compatibility` | Descriptive metadata shown in **Overview**. | | `allowed-tools` | Preserved metadata, not an enforced tool restriction. It neither grants tools nor changes the user's access. | 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] 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 [#limits] The BSQAI API applies these default tenant limits: | Limit | Default | | ------------------------------------------- | ------- | | Uploaded file | 20 MiB | | Total file content after archive extraction | 20 MiB | | Files per package, including `SKILL.md` | 200 | | Skill catalogue offered to the assistant | 16 KiB | | Supporting text per resource read | 64 KiB | 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: | Editor limit | Maximum | | -------------------------------------------- | ---------------- | | Package size in the browser | 20 MiB | | Files | 200 | | `SKILL.md` size | 2 MiB | | Text file size for preview or direct editing | 2 MiB | | Relative path length | 1,024 characters | | Each path segment | 255 characters | 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 [#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](/docs/reference/roles-permissions/skill): | Action | Permission | | ------------------------------- | -------------- | | Read, download, or select | `skill.read` | | Upload or copy | `skill.create` | | Save or update an owned skill | `skill.update` | | Share or unshare an owned skill | `skill.share` | | Delete an owned skill | `skill.delete` | 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 [#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 [#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 [#validation-errors] | Error code | Meaning | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `skill_package_invalid` | The package format, frontmatter, entry point, or file paths are invalid. The detail identifies the problem. | | `skill_package_too_large` | The uploaded file exceeds the tenant limit. | | `skill_package_expanded_too_large` | Extracted file content exceeds the tenant limit. | | `skill_package_too_many_files` | The package exceeds the file-count limit. | | `skill_name_conflict` | The creator already uses the name in this organization. | | `skill_save_conflict` | A newer revision exists than the base revision of the save. | ## Related pages [#related-pages] * [Use skills in chat](/docs/ai/skills/use-in-chat) * [Upload and manage skills](/docs/ai/skills/manage-skills)