Skills

Polyant has three skill surfaces: the per-agent Skills section (covered first), the organization’s catalogue in the sidebar, and the platform catalogue in the Admin Console.

A skill is owned by an organization or by the platform - never by the deployment at large. Two organizations on the same engine keep separate catalogues.

Per-agent Skills section

The Skills section of an agent (its Behaviour group) is where you attach skills from the catalogue to that agent.

What you see

A two-column layout:

• Left column. Every skill the organization can see - its own, plus any the platform has granted it. Each row shows the skill name, category, version, and an enable switch.
• Right column. The currently enabled skills for this instance, with version pins and an env-vars button.

Enabling a skill

Toggling a skill on does three things:

1. Inserts a row in instance_skills linking this agent to that skill.
2. Pins the current version of the skill (semantic versioning). Future bumps to the global skill do not auto-apply - you upgrade explicitly.
3. Recomputes the per-agent tool set: tools declared as skillTools for this skill become enabled.

Configuring environment variables

Skills can declare required environment variables in their YAML frontmatter:

---
name: hubspot
description: HubSpot CRM operations
requiredEnv:
  - name: HUBSPOT_API_KEY
    description: HubSpot private app token (Bearer)
    sensitive: true
  - name: HUBSPOT_PORTAL_ID
    description: Numeric portal id, used in deep links
    sensitive: false
---

For each enabled skill, click the environment variables button to open a dialog. You will see one row per requiredEnv entry. Sensitive entries hide the value behind a password input; non-sensitive entries show in clear text.

Values are stored per agent and skill. Sensitive entries are encrypted at rest with AES-256-GCM using the engine’s ENCRYPTION_KEY; readSkill shows only {{skill_env.<skill>.<KEY>}}, and the runtime resolves that placeholder immediately before an eligible in-process tool executes. The engine records the placeholder in tool and audit arguments. Non-sensitive settings may remain visible, and runSkillScript receives its environment only in the child process when the script runs. A tool that returns a resolved value, or a script that prints one, can still expose it in its result.

Versioning and pinning

Skills are versioned semantically (e.g. 1.4.2). When the catalogue ships a new version, you have to explicitly upgrade. Click the version dropdown next to the skill name and pick the new version. The change is persisted on save.

Pinning protects production: a skill author can publish a breaking change without breaking every instance that has the skill enabled.

Disabling

Toggling a skill off removes the instance_skills row. The encrypted env vars are kept (for restoration) unless you click Clear env vars explicitly.

The organization’s catalogue

The Skills entry in the sidebar (/organizations/{org}/skills) is the organization’s own catalogue. Reading it needs skill.catalog:read - every role holds it, Viewer included; authoring needs skill.catalog:write, which is Admin and above.

It sits with the daily work rather than in Settings because that is where it is used from: browsing and assigning a skill is everyday work, while creating and versioning one is the administrative part of the same page.

A skill in the catalogue is assignable anywhere in the organization, but it is not automatically available everywhere: it reaches an agent only in a workspace it has been assigned to. Being in the catalogue is the first of two boundaries - see What a workspace may draw on.

What a skill is

A skill is a bundle of:

• Slug + name + description + category.
• One or more versions. Each version has a content blob (the skill’s prompt + script bundle) and metadata.
• A list of tools the skill enables when active (the skillTools link).
• Required environment variables. Declared in YAML frontmatter; their values are configured per instance.

CRUD

• List. Tabular: name, category, description, version count, status.
• Create. Click New skill. Fill in the slug (URL-safe, immutable), the human-readable name, the description (one or two sentences), the category. Save. The skill starts at version 1.0.0.
• Edit. Click a row. The detail page lets you edit name, description, category, current version pointer, and status. The version content itself is edited in a code-style editor.
• Add a version. Use the New version button on the detail page. Bump the semantic version (e.g. 1.0.0 → 1.1.0). Old versions remain available - instances pinned to 1.0.0 continue using 1.0.0 until you upgrade them.
• Delete. Removes the skill and all its versions. Instances that had this skill enabled have it cleared automatically.

Importing skill bundles

The catalog supports importing JSON bundles. Use this to share a skill set across deployments or to onboard from a marketplace. Click Import, choose the JSON file, confirm the diff (any conflicting slugs are flagged), import.

There is no catalog-level Export button in this screen, but the endpoints exist: GET /api/organizations/{org}/skills/catalog/export for the whole catalogue and GET .../skills/{name}/export for one skill. See Export and import an agent.

Categories

Skills are grouped by category for ergonomics: crm, comms, productivity, internal, experimental, etc. Categories are free-form strings; the catalog renders them as filter chips at the top.

The platform catalogue

Admin Console → Platform skills (/platform/settings/skills) holds skills owned by the installation, and hands them out per organization. It is platform-admin-only - a grantable right to widen a tenant’s capabilities would itself be a privilege-escalation surface, so this is a role check rather than a permission.

The page lists one row per skill with a “granted to N organizations” count that opens a searchable dialog of switches. A column per organization was tried and grows sideways with the tenant roster.

Its create and edit pages are the organization catalogue’s own editor, reused - not a second one.

What a grant means

A platform skill is visible to no organization until it is granted, exactly like an installed plugin. Once granted:

• Reads are the union of what the organization owns and what it has been granted.
• Writes stay owner-exact. Editing or archiving a granted platform skill is refused 403, not 404 - the organization can legitimately see the row, so pretending it does not exist would be a lie.
• A granted skill is viewable at the organization’s own detail page, read-only. What that view removes is precisely what the engine would refuse: Save, the archive control, the single-skill export, and the authoring-only affordances (env-var editing, the changelog). The Versions tab is fully readable.
• On a slug collision the organization’s own skill wins. That is a safety property, not a preference: a grant is additive and must never change what an agent already resolves. Creating your own skill under a platform skill’s slug is how you override it, and the catalogue then renders one row for that slug, marked as overriding.

Revoking

Revoking a grant stops the skill being served, not merely listed. The runtime checks visibility on every use - when building the prompt, when reading a skill, and when executing a skill’s script - with the organization resolved from the agent’s own workspace, and it fails closed.

The agents’ instance_skills rows deliberately survive a revoke, so a re-grant restores every agent’s configuration exactly. That is why the assignment alone is never treated as authority.

The two boundaries, together

Visibility is an intersection, evaluated on every use:

The order matters for the failure you will actually meet: a workspace row surviving an organization-level revoke does not bring the skill back, because the organization half is checked too. Assign the workspace from Workspaces → Skills; grant the organization from this page or from the platform catalogue.