Skills in Cortex
Pick a skill with / when you write to Cortex, see which skills an answer used, save a skill from a conversation, browse, write, import, fork and share skills under You › Skills, and decide share requests under You › Activity.
Skills are saved instructions that Cortex can follow. In the Matrix workspace you can choose one yourself before you send a message, check afterwards which skills an answer used, save what worked in a conversation as a skill, and browse, write, fork and share skills under You › Skills.
Use a skill with /
Type / in the message box, at the start of the message or after a space, and a
list of skills opens above it. Keep typing to narrow the list.
Where it opens. In every conversation where @cortex or an agent persona
can answer: channels, workspace rooms, direct messages, group conversations,
your own chat with Cortex and your conversations with an agent persona. It does
not open when you edit a message you already sent: there, / is just text.
What is listed. The skills you are offered in that conversation: your own, the ones shared with your groups, and your organization's. Only skills rated at or below the conversation's classification are listed, so a skill classified above the conversation is not in the list. The list says so at the bottom. If nothing is offered you see "No skills are offered here", and if your search matches nothing, "No skill matches" followed by what you typed. If the list cannot be loaded, the palette says "Skills could not be loaded" and you can still send your message.
Each row shows:
- the skill's title and a short description;
- an origin badge: Mine, the name of the group it is shared with (Team when the name is not known), or Organisation;
- the version, such as
v3; - a Runs code badge when the skill runs code.
A skill that runs code is listed last, drawn muted and labelled Runs in agents only: Cortex has no sandbox to run its scripts, so Enter and a click do nothing on that row. An agent whose step has sandbox tools can use it (see Skills that run code).
Keys. Press the up and down arrows to move, Enter or Tab to use the skill (as in the @ list), → to preview it and Esc to close the list. You can also click a row. → opens the selected version's instructions under the list, and ← closes them; otherwise both arrows move the cursor as usual. If the instructions cannot be shown, the preview says "This skill could not be shown". While the list has nothing to choose, Enter sends your message as usual.
Picks. Choosing a skill replaces what you typed after / with the skill's
name, and adds a chip for it above the message. Remove a skill by deleting its
name from the text or by removing its chip. You can pick at most 3 skills per
message. Choose a fourth and the list closes, nothing is added, and you are
told "Up to 3 skills per message".
What happens when you send. The picks travel with the message, so Cortex knows which version of each skill you chose. If you press Try again on an answer, the picks of the original message are sent again with it. A message sent without picks is exactly the message it would have been without this feature.
A pick asks Cortex to use the skill; it does not widen what you may use. Cortex loads a pick only if it is still one of the skills you are offered in that conversation, and ignores it otherwise.
See which skills an answer used
When a Cortex reply used skills, a chip for each one appears under the reply: Used Weekly report v3 · from Finance. The chip names the skill, the version, and where it came from:
| Chip says | The skill is |
|---|---|
| from your skills | one of yours |
| from Group | shared with that group |
| from your organisation | your organization's |
| from Name's pinned skills | pinned to that agent |
| from the Name extension | provided by an extension |
Chips appear only under replies from Cortex or one of your organization's agents, and show up to 10 skills.
Select a chip to open its details:
- Fingerprint: the first characters of the version's fingerprint. The copy button copies the whole value.
- Source: how the skill entered the library: written in Cortex, uploaded, imported from Git, imported from an archive, or from an extension.
- Approved by: the people who approved this version, or "No approvals recorded".
- Classification: the skill's rating, and whether it is above or within the conversation's classification.
- Runs code: Yes or No.
- Checks: whether the automatic checks passed or flagged the version for review, and how many files it holds.
- Tools: the tools the skill asked for. A tool the agent was not allowed to use shows as "name — not given to this agent".
The details are fetched when you open the chip. If they cannot be loaded, the popover says so and keeps the title, version, origin and tools.
A skill you may not read. A personal skill belongs to its author. When another person's skill was used in an answer you can see, you still get the chip, but its popover says "You can't open this version, so only what this answer says about it is shown." You then see the title, version, origin and tools the answer records, without the fingerprint, source, approvals or checks.
Skills that run code
Some skills bring scripts with them, not only instructions. Such a skill runs only inside an agent's sandbox, and only when all of these are true:
- your organization allows skills that run code, at or below the conversation's classification (Settings › Cortex › Skill settings);
- the agent's step runs in the isolated sandbox and has its sandbox tools: a step that declared no tools never receives a skill that runs code;
- the version can run: it is at most 2 MiB, and every dependency is locked by
hash. A
requirements.txtpins each package with==and a--hash=sha256:; apackage.jsonthat declares dependencies has apackage-lock.jsonbeside it with an integrity hash for each one.
When the agent loads such a skill, the sandbox receives its files, checks them against the approved version's fingerprint, and puts them in a read-only folder. The sandbox then installs the locked dependencies itself, without running any package's install scripts. If a file does not match, or a dependency does not install, the skill is not loaded. If the skill's files change during the step, the agent can no longer run commands in that step, and the skill's use is recorded as modified after load.
A skill that runs code that you pick with / for an agent is not loaded before
the agent starts, the way a skill that only instructs is. The agent is told
that you picked it and loads it itself, because only that load puts the skill's
files in its sandbox. A pick that runs code counts only when you are offered it
in that step; one you are not, or one at an older version than you are offered,
is left out.
An agent can be given a skill that runs code as one of its pinned skills. The same conditions are checked each time the agent loads it, not when it is pinned: on a step that does not run in the isolated sandbox, or after your organization stops allowing skills that run code, the load is refused and the run says why. A version saved before skills could run code is checked the same way when it is loaded.
An agent's skills
An agent persona loads a list of skills, each pinned at a version. In your conversation with the agent, open the room details and choose the Skills tab. It is only there in a conversation with an agent persona.
The pinned skills are one table, a row per skill: its title, the version it is
pinned at, Runs code when it brings scripts, and No longer shared when
its share was pulled back (the agent stops loading it). A pin never moves by
itself: when a newer version is approved and you may pin it, the row offers
Update to vN, which first shows what changed in SKILL.md and moves the
pin only when you confirm.
- Add a skill, above the table, opens a search over your own skills that can be used in this conversation, at its classification. Choosing one pins it; a skill already pinned reads Pinned and cannot be chosen again. A skill that runs code pins like any other; a version whose code may not run is refused with a reason.
- Unpin, on each row, asks first, then the agent stops loading the skill.
- Use another agent's list makes this agent load the list of one of your other agents. A change to that list then reaches every agent that uses it, so the list needs a name: if it has none, you give it one.
- A list used by more than one agent says This list is shared with its name. You can Rename it, or Give this agent its own list, a copy only this agent uses.
Only people who may edit the agent's workflow can change its skills. Anyone else who opens the tab sees the list, read-only, with the reason. Every change is recorded in the Audit Log. Organization admins see every agent's list under Settings › Cortex › Agent skill lists.
Skills follow a deploy
An agent whose workflow runs in a read-only environment changes its skills only with a deploy. When you promote a workflow to another environment, the copy there gets its own list holding exactly the skills, at the versions, that the workflow you promoted has pinned. Each pin keeps the person who pinned it and when, so a skill offered to the agent in one environment is offered to it in the next. A change to one environment's list never reaches another's. Pinning or unpinning a skill is a change to deploy on its own: Deploy offers it even when nothing else in the workflow changed, and lists it as "Agent skill pins changed".
- A pinned skill that is archived, no longer shared, or whose scripts may not run does not follow. The deploy still succeeds and says "Deployed, but some pinned skills are archived, no longer shared, or have scripts that may not run, and did not follow the agent."
- If the skills cannot be carried over at all, the deploy still succeeds and says "Deployed, but the agent's pinned skills could not be carried to this environment." The copy keeps the skills it had there. This is also what happens when you promote an older version again whose skills the workflow no longer has pinned at those versions.
- A version promoted before agents had skill lists leaves the copy's list as it is.
The Audit Log records the promotion as yours, names whose pin each skill was, and names the workflow it came from.
Your skills
The top of the sidebar has a You section, above your conversations. It holds
one row, Skills, which opens your skill library in the main area of the
window instead of a conversation. Selecting a conversation closes the library
again. The You section is hidden while you type in the sidebar's search box.
The library also has its own address, ending in ?view=skills, so you can
bookmark it.
The library has three tabs:
- Mine: the skills you wrote, including the ones you forked.
- My groups: the skills shared with the teams you belong to. When a skill reached one of your groups in the last seven days, it is also listed under From your groups this week at the top of the tab.
- Organisation: the skills shared with your whole organization.
Each tab is a table with one line per skill: its name and description, where
it comes from (Mine, the name of the group, or Organisation), its
version such as v3, Approved once one of its shares is live,
Waiting for approval while one of your shares needs approval, Runs code
when the skill runs code, and how often it was used this month.
Mine has a filter above the table: All skills, Approved or Not approved. Approved lists the skills shared with at least one group or with the organisation, whether an approver approved the share or your organisation lets it through without approval. Not approved lists the skills that are private, or whose every share is still waiting for approval. A skill already shared stays Approved while a newer version of it waits. When nothing matches, the tab says "No skills match this filter". My groups and Organisation list only skills that are shared, so they have no filter.
A tab shows one page of skills at a time. When there are more, the arrows under the table go to the next or the previous page; each new page is loaded when you first go to it. An empty tab says so, for example "You have no skills yet", and a tab that cannot be loaded says "Your skills could not be loaded". If a later page cannot be loaded, the page shown stays, with Try again.
Click a row to open the skill in a side panel, with its actions (Share…, Edit, or Fork into Mine) and:
- its title and description;
- its origin, its version, Runs code when the skill runs code, and how often it was used this month, for example "Used 4× this month";
- who a share is waiting for, when one of your shares needs approval: the people by name, "Waits for the group's admins" or "Waits for organisation admins";
- "Unsaved changes, edited …" when you have an unsaved draft of it;
- "Forked from Title vn" for a fork, with the group it came from when that is known.
Fork into Mine
A skill someone else wrote, in My groups or Organisation, has a Fork into Mine button in its side panel. Forking makes a personal copy of that version, which you can then change and share as your own. When it is done you are told "Title is now in Mine", and the library switches to Mine, where the fork now appears.
Open in the editor. After a fork, Mine shows a notice with an Open in the editor button, which opens the fork in the save sheet so you can change it straight away (see Save a skill). Close the notice to leave the fork as it is.
Forking can be refused:
- "This skill is already yours": you cannot fork your own skill.
- "You already have a skill with this name. Rename yours, then fork again."
- "The skill could not be forked": something else went wrong. Nothing was created, and you can try again.
Your own skills have no Fork into Mine button.
Import skills
Import…, next to New skill in Mine, brings in skills you already have. Choose either:
- Choose files or an archive: one zip or tar.gz, or loose files such as a
SKILL.md, a Cursor rule (.mdc) or a GitHub Copilot instructions file; - Choose a folder: a folder holding one or more skill folders.
The upload is read as soon as you pick it, and nothing is saved yet. Each skill it holds is listed:
- a skill that can be imported has a checkbox, and starts chosen. It can carry a Runs code badge, a Has findings badge when the checks found something to note, and "Converted from file" when it was made from a rule file;
- a skill that is not valid says why, in the same words a save uses;
- a skill your organisation's DLP policy blocks says so, and cannot be chosen.
Above the list, Classification starts at your organisation's default. Change lets you pick a level up to your own clearance, for every skill in the import.
Import n skills saves the chosen ones into Mine, each as version 1, and you are told "n skills are now in Mine". They stay yours until you share them. Either all the chosen skills are imported or none is:
- "This upload is larger than 11 MB. Import it in parts."
- "This upload holds more than 64 skills. Import it in parts."
- "This upload is not a folder, zip or tar.gz that can be imported", or "This upload holds no SKILL.md and no Cursor or Copilot rule file".
- "You already have a skill with one of these names. Rename yours, or leave that one out."
- "A skill you chose can no longer be imported. Choose the upload again."
Skills from an extension
An extension can ship skills (see Skills in extensions). When an organisation admin installs it, each of its skills is added to the library with the extension as its author, shown as "Extension id", at version 1 labelled with the extension's version. Nobody is offered it yet: the install opens one request to share each skill with the whole organisation, and the skill is offered only once an organisation admin approves it in You › Activity or under Settings → Cortex → Skill review in the Platform.
The extension is the only place those skills change. Saving a new version of one in Cortex is refused; fork it into Mine to make a copy you can change. A new release of the extension adds a version of each skill whose files changed, and that version reaches a team or the organisation only after its share is approved again. The extension cannot remove its skills: they stay, at their last version, until an organisation admin pulls their shares back.
Share a skill
Share… appears only on the skills you wrote, in Mine. It opens a dialog titled "Who should have it?" that shares the version shown in the side panel:
- Your teams lists the teams you belong to, each with its number of members, followed by The whole organisation. If you are in no team, it says "You are not in any team yet".
- Other teams has a search box. Type part of a team's name to list the matching teams in your organization. A long list of teams has a Show more button.
Being listed does not mean a share will go through. When you choose a target, Cortex first asks what sharing would do, without sharing anything, and says the answer under the lists:
- "Team gets it now. Its admins are told." or "Everyone in the organisation gets it now." The share goes live as soon as you press Share.
- "Waits for …", followed by the people, "the group's admins" or "organisation
admins". The share waits for approval, and the dialog lists why, one sentence
per reason:
- "Sharing with the whole organisation needs an organisation admin's approval."
- "It runs code."
- "Its checks flagged something for review."
- "Your organisation asks for approval before a skill reaches a group."
- "This deployment requires a group admin's approval for every share."
A version that runs code but cannot run (see Skills that run code) cannot be shared: the dialog says "This version runs code that cannot run here, so it cannot be shared" and Share stays off.
The dialog also shows whether the skill's automatic checks passed. You can add an optional reason, Why, for the approvers.
Share stays off until that answer is in. Once you press it, you are told "Title is shared with team", or "Title waits for approval before team gets it". The dialog can also say:
- "This team or organisation already has this version".
- "That team no longer exists in your organisation".
- "What sharing would do could not be checked", when the first answer could not be read, or "The skill could not be shared" after you pressed Share.
A waiting share is decided under You › Activity: see the next section.
Approve, decline and pull back
You › Activity lists the shares that wait for you to decide: the ones headed for a team you administer, or for the whole organisation when you administer it. Each card says who wants to share which version with which team and how many people are in it, quotes their reason, and shows what the item says about the change:
- how many lines were added and removed since the version in use now (a count, not the lines themselves),
- whether the scripts changed,
- whether the automatic checks passed, whether the skill runs code, and how often it was used this month.
Each card has three buttons:
- Approve. You are told "Team now uses Title vn". When the share needs a second approver, you are told it "waits for a second approver" instead, and the team keeps its version until someone else approves. If the request was decided before your click landed — by someone else, or by you in another tab — Cortex says where it stands, for example "Title vn was already declined for Team", and refreshes the list. A version that runs code but cannot run is never approved: you are told "Title runs code that cannot run, so it cannot be approved. You can still decline it."
- Not now hides the card for you, on this device only, and Activity says how many requests you set aside, with Show again. The request still waits, and the other approvers still see it.
- Decline… asks you to confirm, with an optional note for the person who asked. The team keeps the version it uses now.
If you administer the organisation, each card also has See everything, which opens the request in the Platform, under Settings → Cortex → Skill review, with its full review open.
When a share waits for an organisation admin — a share with the whole organisation, a share with a team that has no admin, or the second approval a script needs — every organisation admin except the person who asked gets a notification in their Platform inbox, "A skill share waits for your review", and an email of it unless they turned emails off. It names who asked and whether for the whole organisation or a team, never the skill. Its Review button opens the request under Settings → Cortex → Skill review. A share that waits for a team's own admins notifies those admins the same way, except the person who asked; its Review button opens You › Activity in Cortex, where team admins decide. An extension's share request notifies only once the extension's skill is saved.
Earlier lists the shares that went live into your teams recently, with Pull back. After you confirm, the team goes back to the version it used before ("Team uses Title vn again"), or stops using the skill when there was none ("Team no longer uses Title"). If the team already follows another share, or you can no longer pull this one back, Cortex says so and refreshes the list.
A long list has a Show more button. If the next page cannot be loaded, the cards already shown stay, with Try again in place of the button. When nothing waits, Activity says "Nothing waits for you".
Save a skill from a conversation
When Cortex did something you want it to do the same way next time, keep the method as a skill.
Save as skill. Open the menu on a reply from Cortex or one of your organization's agents and choose Save as skill. It is not on messages people wrote. A sheet titled "Save as a new skill" opens on the right. Cortex drafts the skill from the conversation up to that reply: the draft names the skill, says when to use it and lists the steps. It keeps the method, never the data. Files and images are not part of the draft. The draft uses the latest 40 messages at most; when some of those are too long to fit, the sheet says how many were left out.
Keep your corrections. When a reply used one of your own skills and you corrected it straight away, Cortex offers under its answer to your corrections: "You corrected 2 things. Keep the changes in Title?" Only the messages you wrote before Cortex answered count as corrections; what you write after that, such as a new question later on, does not. Save as vn opens the sheet on a new version of that skill, drafted from the conversation up to your last correction and Cortex's answer to it. Not now hides the offer for you, on this device. A skill version is offered once, under the first reply you corrected, and the offer goes away once the skill has a newer version. It is never offered for a skill shared with a group or with your organization: changing one of those is up to its author. It is also not offered when the reply was made for someone else, or when another agent answered your corrections.
From the library. Under You › Skills, Mine has a New skill button, and each skill you wrote has Edit. Both open the same sheet with nothing to draft from, on the editor: Edit on the skill's latest version, New skill on an empty one.
What the sheet shows
- What changes: the changes to the skill's
SKILL.md, grouped under the heading they fall under, with removed lines marked − and added lines +. A new skill shows its whole text. - Edit the wording: tell Cortex how the draft should change ("shorter
steps") and choose Draft again. Open the full editor lets you edit
SKILL.mdyourself. Under the editor, a line says straight away when the text is not a valid skill yet, for example when the header has no name. - Why: an optional note on what you changed and why. It goes with the version to whoever approves a share. Up to 1,000 characters.
- Filled in for you:
- Classification. Saved from a conversation, the skill takes that room's classification, and you cannot change it here. Saved from the library, it starts at your organization's default; Change lets you pick another one, up to your own clearance.
- Runs code, when the skill contains code. When it cannot run, the sheet says why: "Runs code and is larger than 2 MiB, so it cannot run", or "Runs code that does not lock every dependency by hash (file), so it cannot run".
- Tools: the tools the skill asks for.
- "unchanged since vn" when all three are the same as in the version you are changing.
- Checks: "Checks passed", or what the automatic checks flagged for review, such as a hidden character, a classification below the room the skill came from or below an earlier version of the skill, or a match on your organization's data-protection rules.
Saving
Save saves the version to Mine, and you are told "Saved Title vn". When the skill is already shared with groups, the main button is Save & share with those groups, with a note such as "Finance uses v4 until v5 is shared." (or "… use earlier versions …" when the groups use different versions). It saves the version and then shares it with each of them, one notice per group. A share can go live or wait for approval, exactly as with Share…. A skill not yet shared with anyone offers Share… as soon as it is saved, so you do not have to go back to the library.
Your draft is kept. What you type is kept as a draft shortly after you stop typing and when you close the sheet, one draft per skill and one for a new skill. The sheet says "Draft kept". If a draft could not be kept, it says so and keeps your text; it tries again on your next change and when you close the sheet. Meanwhile the skill in Mine says "Unsaved changes" when you open it.
When you open the sheet for that skill again in the same place, it asks whether to Resume the draft or Discard it. Discard deletes the draft. A draft is offered back only where it was kept: one kept in a conversation is offered in that conversation, and one kept from You › Skills only there, so a draft never moves to a room with a lower classification.
Once a version is saved, the sheet no longer changes it: the editor and Why are read-only. Close the sheet and choose Edit to start the next version.
When a save is refused, the sheet says why and keeps your text:
- "Someone saved vn first." Reload puts your text on top of the newest version; save again to keep it.
- "This is not a valid skill yet. Fix the line under the editor, then save again."
- "A new version keeps the skill's name. Put the name back, then save again."
- "Nothing changed since the last version".
- "That classification is above your clearance".
- "This room's classification could not be read, so nothing was saved".
- "You already have a skill with this name", for a new skill.