Skills in extensions
Ship Agent Skills inside a Scrydon extension. Installing the extension adds each skill to the organization's Skill Library, where an org admin approves it before anyone is offered it.
This artifact ships inside an Extension. For the shared lifecycle — extension build, upload, install — see Extensions & Authoring SDK.
A skill content entry ships an Agent Skills folder: a SKILL.md with instructions, plus any files the skill uses, scripts included. When an organization installs the extension, each skill becomes a skill in that organization's Skill Library. It is read-only, and it is versioned by your extension's releases. Nobody is offered it until an org admin approves it.
Layout
Each skill is a folder next to your extension's entry file. List the folders in provides.skills:
aml-skills/
├── index.ts
└── skill-sar-narrative/
├── SKILL.md
└── scripts/
└── total.pyimport { defineExtension } from "@scrydon/sdk-authoring/extensions";
export default defineExtension({
id: "aml-skills",
name: "AML Skills",
version: "1.0.0",
logo: "<svg …/>",
provides: { skills: ["skill-sar-narrative"] },
});---
name: sar-narrative
description: Drafts the narrative section of a suspicious activity report from case notes and a transaction list. Use when an analyst asks for a SAR narrative.
---
# SAR narrative
Write the narrative in five parts, in this order: …provides.skills takes paths only. A skill has no inline form, because it is a folder, not a definition. extension build copies every file of each folder into the archive as it is: a .ts or .py file in a skill is a script for the agent, and the build never compiles it.
A complete example lives in the SDK at src/extensions/container/examples/aml-skills/.
One skill per entry
Each path in provides.skills is one skill:
- the path is a single folder name directly under the entry file, not a nested path;
SKILL.mdsits at the root of that folder. A folder without one failsextension validateandextension buildwithsubdir_missing_skill_md;- the skill ships at the extension's version. A skill folder has no manifest, so it never declares a version of its own.
An extension can list as many skills as it needs, and can mix them with any other content kind.
The name
The name in the frontmatter of SKILL.md identifies the skill, not the folder name. It follows the Agent Skills rule: lowercase letters, digits and single hyphens, at most 64 characters. An extension skill's name must also start with a letter. A name such as 9-step-review is refused at upload with skill_name_not_content_id.
Keep the name stable across releases. The organization's library keeps one skill per extension and name, so renaming a skill in a later release adds a second skill rather than a new version of the first. Two different extensions can ship the same name without colliding.
description is required too, at most 1,024 characters. It is what Cortex shows when someone picks a skill, so say what the skill does and when to use it.
extension validate checks the layout only. The platform reads the frontmatter when you upload the archive. A bad frontmatter is caught there, not offline.
Limits
A skill folder holds at most 200 files and 8 MiB in total, with at most 1 MiB per file. SKILL.md is at most 64 KiB. The archive's own limits apply on top of these: 400 files and 5 MiB per file across the whole extension.
Scripts and lockfiles
A skill can bring scripts (.py, .sh, .js, .ts, .rb, .ps1). Such a skill runs code, and it follows the same rules as every other skill that runs code in the Skill Library (see Skills that run code):
- it runs only inside an agent's isolated sandbox, and only when the organization allows skills that run code;
- the folder is at most 2 MiB;
- every dependency is locked by hash. A
requirements.txtpins each package with==and a--hash=sha256:. Apackage.jsonthat declares dependencies needs apackage-lock.jsonbeside it, with an integrity hash for each one.
Lockfiles and other non-code files under a skill folder (requirements.txt, package-lock.json, data files) are admitted in the archive because they sit under a declared skill path. The same file anywhere else in the extension is refused, as before.
A skill that runs code but cannot run, for example because a dependency is not locked, still installs. It is marked as not runnable, it cannot be approved, and it is never offered to anyone. Scripts that use only the language's standard library need no lockfile.
What install does
When an org admin installs the extension from Add extension, each skill is written into the organization's Skill Library:
- with the extension as its author, shown as "Extension id" in the Skill Library and in Review;
- at version 1, labelled with the extension's version;
- at the organization's lowest classification.
Install does not offer the skill to anyone. It opens one pending request to share the skill with the whole organization, which waits in Settings › Cortex › Skill review and in Cortex under You › Activity for the organization's admins. Only when an org admin approves the request is the skill offered to the organization. The extension's Includes tab lists each skill and the version the library holds.
An archive you upload yourself, from Sources › Upload an extension, lists each skill it holds, with its name and description, before you upload it.
Under the NATO profile, which requires signed extension sources, an extension from a source that is not signed cannot be installed, so none of its skills reach the library. Skills have no signature check of their own: they inherit the extension's.
Nobody can change an extension skill in the library. Saving a new version of it is refused; a member who wants to change it forks it into Mine and edits the copy.
Updates
Installing a new release of the extension adds a new version of each skill whose folder changed, labelled with the new extension version. A folder whose files are unchanged adds no version.
A new release reaches the library only when an administrator installs it, from Add Extension or Sync. The scheduled update that keeps other installed extension content current does not install skills.
When a sync of the extension source finds a release whose skill folders the library already holds, and the rest of its content is installed, it skips that extension, so no admin is asked to approve an install that would write nothing.
A skill belongs to the source that wrote it. If another source publishes an extension with the same id, or someone uploads it by hand, installing it is refused with skill_lineage_contested while the library holds a version from the first source. The message names both spellings of the extension.
A new version never reaches anyone by itself. Wherever the skill is already shared, the share keeps the version it was approved at, and a new request waits for approval of the new version, under the usual rules. Retrying the same install returns the same versions instead of writing them again.
No uninstall
An extension skill cannot be removed by the extension. When the organization stops using the extension, or a later release drops a skill, the skill stays in the library at its last version, and every share stays in place. To stop offering it, an org admin pulls the share back from the Skill Library.