Skip to main content
A Skill is a reusable, versioned package of instructions and supporting resources. It is neither a callable application tool, an MCP server, extra system-prompt text, nor a file uploaded to one run.

​
Choose the right primitive

A Skill can teach the model when and how to call a tool, but it does not grant that tool or bypass its authorization. Likewise, storing a document in a sandbox does not turn it into a Skill. A Harness Operation may ask its temporary scratch loop to activate a relevant Skill, but it cannot attach one. Every operation inherits the complete catalog already mounted on the parent Agent version; activate_skill remains progressive prompt behavior rather than a hard operation-to-Skill binding.

​
Version binding and session inheritance

OAO stores Skills in PostgreSQL and binds exact Skill version IDs to immutable agent versions. When you create a session, OAO copies those bindings to the session automatically. You do not send Skills again at session creation.
Publishing version 2 of a Skill does not change an agent that references version 1. Publish a new agent version and select version 2 when you want new sessions to use it. Existing sessions remain on their recorded agent and Skill versions. The binding is therefore made when an agent version is published, not every time a session starts. A new session created from an agent automatically inherits the exact Skill versions on the selected agent version. Session creation does not accept a mutable “latest Skill” pointer and does not require the caller to repeat the Skill list.

​
Package contract

Create and version requests use a provider-neutral JSON representation:
name and description are the small discovery entry visible to the model. instructions is the equivalent of the package’s SKILL.md body. Files may represent references/, templates/, assets/, or scripts/; their relative paths are preserved. allowedTools is optional compatibility metadata and is not an authorization control.

​
Resource workspace

The console provides a small package file manager instead of a single path/content field. You can create folders, create Markdown files, upload multiple .md files, select a file to edit and preview, and remove a file or a complete folder tree.
Folders and files use package-relative authoring paths. For example, references/customers/acme.md means “the acme.md resource inside the references/customers package folders.” It is not a path on your workstation, in Daytona, or in the model’s runtime tools. The MVP editor accepts UTF-8 Markdown files. The direct package API remains provider-neutral and represents every resource as { path, contentType, dataBase64 } in the files array. Keep the main instructions focused on the procedure and tell the model which supporting material to consult. Put bulky details that are needed only for some requests in references. Do not put a rule in a reference if the model must follow that rule on every activation unless the instructions explicitly require reading the file. For example, create references/carrier-codes.md in the workspace with:
references/carrier-codes.md
Then include this direction in the Skill instructions:

​
Drafts and immutable publication

The file manager edits a PostgreSQL-authoritative Skill draft. A draft is a mutable staging resource; it is not available to agents. Publishing validates the complete draft and copies its files atomically into a new immutable Skill version. When you choose Publish new version, OAO clones the selected Skill version into a new draft. Editing, moving, or removing its resources never changes the source version. Empty folders may exist in a draft but are discarded at publication because published package directories are reconstructed from file paths. Draft file contents, hashes, tenant identity, revision, and lifecycle remain in PostgreSQL. Draft operations require skill:write; reading or listing drafts requires skill:read. Publication emits the normal skill.created and skill.version_published events without placing instructions or file contents in event or audit payloads. Validation enforces:
  • a lowercase, hyphenated Skill name and key;
  • no more than 128 resource files;
  • no file larger than 5 MiB and no expanded package larger than 10 MiB;
  • canonical base64 and a declared media type for every resource;
  • normalized, relative paths without .., backslashes, control characters, empty components, case-folding collisions, or a resource named SKILL.md;
  • a SHA-256 for every file and a canonical SHA-256 for the complete version.
PostgreSQL contains the instruction text, file bytes, checksums, lifecycle, and tenant identity. Export returns the exact version and resources needed for a portable backup or import into another project. OAO does not extract archives, follow symlinks, or fetch remote package content.

​
Download and upload bundles

The console wraps export in a portable bundle file, <key>-v<version>.skill.json:
  • Download on any version of a Skill produces this file from the export route.
  • Upload Skill on the Skills page turns a bundle into a new draft; Upload version on a Skill page turns it into a draft of the next version of that Skill, replacing the packaged resources with the bundle’s. Both open the usual review dialog, so nothing is published until you confirm.
  • Uploads accept only Markdown resources (.md, text/markdown); a bundle with other file types, or a file that is not a bundle, is rejected with the reason and no draft is left behind.

​
Progressive disclosure

OAO uses the Skill primitives in the pinned Flue 2.0.3 runtime:
  1. Admission resolves only the exact Skill versions recorded on the session.
  2. OAO verifies tenant identity, lifecycle, package hash, file hashes, and byte limits before registering immutable Flue definitions.
  3. Flue exposes only each Skill’s name and description in its discovery catalog.
  4. The model calls Flue’s activate_skill when that catalog entry is relevant. Full Markdown instructions become available only at activation.
  5. The model calls read_skill_resource for a supporting file only when it needs that resource.
This keeps complete instructions and resources out of the initial system prompt. OAO emits redacted skill.activated and skill.resource_read events for debugging; file contents and instructions are not copied into product events or audit details. OAO does not discover application Skills from a Daytona workspace. The Flue filesystem path .agents/skills is hidden from runtime discovery so a mutable or restored workspace cannot override the PostgreSQL binding. Skill resources are served from the verified runtime registry; they are not materialized into the persistent workspace in this MVP. After activation, Flue lists each supporting file with an exact, read-only virtual path similar to:
The model must pass the advertised virtual path exactly to read_skill_resource. The package-relative value entered in the console is the stable authoring path; Flue adds the runtime prefix when mounting the verified package. The virtual file is served from the in-memory runtime catalog backed by PostgreSQL. It is not copied into Daytona, cannot be edited, and is not visible to shell commands.

​
Console workflow

  1. Open Skills and choose Create Skill, or Upload Skill to start from a downloaded bundle.
  2. Enter a routing-friendly name and description. The description should say what the Skill does and when the model should activate it.
  3. Write the Markdown instructions.
  4. In Resource workspace, create package folders and Markdown files, or select a folder and upload multiple .md files. Select any file to edit and preview its complete rendered Markdown.
  5. Publish the Skill, then create or publish an agent version and select the exact Skill version to attach.
  6. Start a session from that agent. The session inherits the binding; do not submit the Skill again.
  7. Inspect the session timeline for skill.activated and, when a reference was needed, skill.resource_read.
When publishing an update, review the complete rendered instructions and reference content before selecting the new version on a new agent version. Older agents and sessions remain pinned to their previous Skill versions.

​
Troubleshoot supporting-file reads

If activation succeeds but read_skill_resource reports that the packaged Skill file was not found, inspect the tool call in the session timeline. The most common cause is passing the authoring path directly:
Incorrect
Activate the Skill first and copy the exact virtual path included in its activation result:
Correct
Also verify that the file appears in the published version’s read-only resource tree. Correct the package by publishing a new Skill version and a new agent version; existing versions are not edited in place.

​
Lifecycle

Every new Skill version starts active.
  • active versions can be attached to a new agent version.
  • deprecated versions cannot be newly attached, but an existing session may continue using one.
  • revoked versions cannot be attached or admitted to a run. A session that references one fails safely during admission until an operator creates a new session from an agent version with an allowed Skill version.
Lifecycle only moves forward: active to deprecated or revoked, and deprecated to revoked. Version rows, contents, checksums, agent bindings, and session bindings are immutable.

​
Disable or remove a whole Skill

Version lifecycle is per version. Two Skill-level controls cover the whole package, from the row actions in the Skills list, from the Skill page, or through the API:
  • Disable Skill pauses it. No new agent version can attach any of its versions until the Skill is enabled again. Published agent versions that pin it keep running with it: thread incarnations pin an immutable snapshot of the bound Skill set, so nothing changes mid-session. The agent editor keeps showing a disabled Skill only while the version being edited pins it, so the operator knows to unselect or re-enable it before publishing.
  • Remove Skill archives it permanently. The Skill leaves the list and the agent picker, its open drafts are discarded, and its key becomes free for a new Skill. Published versions stay stored because agent versions and session history reference them, so agents that pin them keep working. To also stop existing sessions from using a version, revoke that version.
Both actions confirm before they run and require skill:revoke.
Resource files under scripts/ are data only. OAO never executes a Skill script automatically. A model could read a script and separately request an enabled sandbox shell tool, so normal sandbox capability, approval, secret, and network-egress controls still apply.

​
Authorization

Project-scoped actions are skill:read, skill:write, skill:bind, and skill:revoke. Publishing an agent version also requires agent:write and validates every selected Skill version within the same tenant transaction. The console provides API parity for listing and creating Skills, publishing new versions, deprecating or revoking versions, disabling, enabling, and removing Skills, selecting exact versions on a new agent version, and viewing the Skill versions inherited by a session.

​
Package integrity and startup failures

Publication and runtime activation use the same canonical file ordering when calculating a Skill package hash. New hashes use version 2 serialization with locale-independent UTF-16 code-unit ordering for file paths and object keys. Database collation, ICU settings and resource enumeration order do not change that hash. Activation also accepts version 1 hashes from the original en-US publication runtime using its explicitly pinned legacy ordering; existing immutable packages from that runtime need no migration or republication. Publish only intended source resources. Exclude generated caches such as __pycache__, compiled files and local development artifacts. Verify a published package by starting an isolated session, in addition to comparing exported bytes. For a run that has not reserved an admission, if a bound Skill is revoked or fails its package integrity validation during activation, admission marks the run failed with skill_package_unavailable and a safe explanation. Cancellation of a run with a durable admission receipt still reconciles and aborts its Flue incarnation, even if its Skill was revoked. An ambiguous dispatch without a receipt still requires activation so a replacement worker can finish admission recovery before aborting. The startup failure path never removes an existing admission or settles a running agent. It does not leave a new run queued until wake retries are exhausted. Temporary database failures remain retryable. Genuine corrupt packages require a corrected Skill and agent version followed by a new session; existing sessions keep their original version bindings. Deploy the upgraded worker before the API so it accepts both hash formats before new version 2 packages can be published. After version 2 packages exist, do not roll back to a worker that only understands version 1.