Skills: reusable procedures for agents

Availability

The organization policy also decides whether personal skills may be attached to the organization's agents, whether marketplace skills are allowed, whether scripts may run, whether suggested skills are drafted from members' conversations, the default approval mode, the cap of skills per agent (12 by default, at most 20) and a list of blocked skill names.

What a skill is

A skill is a folder. SKILL.md at its root carries frontmatter and the instructions; the other folders hold what the instructions refer to. Akili reads the standard fields and four of its own under metadata.

---
name: board-update
description: Draft a quarterly board update from the metrics and notes the user provides. Use when asked for a board update, investor update or quarterly summary.
allowed-tools: code_interpreter
metadata:
  akili-approval: ask_write
  akili-user-invocable: "true"
  akili-model-invocable: "true"
---

# Board update

1. Read references/structure.md for the section order.
2. Ask for the quarter's metrics if none were attached.
3. Write the update in the brand voice in references/voice.md.

The library card for each skill shows its scope (personal, workspace, marketplace or built-in), the latest version and status, a security scan badge (Scan passed, Scan: review, Scan: blocked or Scan pending), how many agents use it, and counts of references, scripts and assets with the approximate tokens it costs when loaded.

Create or import a skill

1. Step 101

   New skill

   On the Skills page choose New skill. Name: lowercase letters, digits and single hyphens; this is also the /command. Description: when should the agent reach for this skill, in one or two sentences. Scope: Personal, Workspace or Marketplace. You can also start from a saved prompt: its text becomes the body.
2. Step 202

   Or import a zip

   Import .zip takes a package with SKILL.md at its root. A name that already exists is refused; rename it in SKILL.md and import again. Export .zip on any card produces the same format.
3. Step 303

   Or import from Git

   Import from Git… takes a public GitHub repository URL (https://github.com/<owner>/<repo>; other hosts are refused), the full 40-character commit SHA (branches and tags are not accepted) and the path to the folder holding SKILL.md, relative to the repository root.
4. Step 404

   Or let Akili suggest one

   When the organization enables suggestions, the Suggested filter lists skills drafted from recurring work in your own conversations, with the source conversations and a ready trigger set. Review draft opens it; Not useful hides it. A suggestion is never attached to an agent without you.

From the agent builder's Skills section you can also Create a skill or Upload .zip; the new skill is attached to that agent straight away, up to the agent's cap.

Edit the files

The editor opens on the draft. The Files tab lists the package: Add file (a relative path inside the package, such as references/notes.md), Upload and Delete. Edits save when you leave the editor. A meter under the body shows its lines and approximate tokens and the index cost (the one-line entry every turn pays); past the limit it warns Long body: over {limit} tokens. Move detail into references/. The header says Validates or Invalid, and shows the scan state.

The Settings tab holds tags (up to 10), an icon, the two invocation switches (People can invoke it with /name, The model can load it on its own), the approval mode (Never ask, Ask before write actions, Ask before every action, stored as metadata.akili-approval) and Delete skill, which also removes published versions and detaches the skill from every agent.

Typed arguments

Under Arguments, declare the values the skill accepts: a name (letters, digits, _ or -, starting with a letter), a type (Text, Number, Choice with comma-separated choices, or File), whether it is required, and a description. Akili stores them as a JSON Schema in metadata.akili-arguments.

• In chat, choosing the skill with / opens a small form, {name} needs a few values, with validation for required fields, numbers and ranges; a File argument takes the name of an attached file.
• In Flows, the run_skill node binds each argument to the output of an earlier step.
• Without arguments, free text after the command still reaches the skill as $ARGUMENTS.

Versions, review and publishing

Publish version freezes the draft into v1, v2, … with a checksum. Published versions are immutable: to change anything, edit the draft and publish again. The Versions tab lists each version with its status, scan result, health, drift and the tokens it costs, and offers Re-validate.

Who reviews what

• Personal skills are approved on publish; only you (and the agents you own) use them, and an organization can keep them off its agents.
• Workspace skills are frozen as In review (Submit for review) and wait for an organization admin, who approves, asks for changes or rejects with a review note. The Needs review filter on the Skills page is the admin's queue.
• Marketplace skills ship inside a marketplace listing and are reviewed with it; installers receive a snapshot of the approved version.
• Regression gate. A version whose evaluation scores drop more than the organization's threshold below the last approved version fails the gate: Regression gate failed — approval needs an admin override, recorded with who overrode it and why.

Attach skills to agents

The Skills section of the agent builder reads Procedures the agent loads only when a task calls for them. Attach from library picks up to the remaining slots; the panel shows {attached} of {cap} attached · ~{tokens} tokens per turn.

• Readiness. Each attached skill shows Ready, Setup required or Blocked. A skill cannot grant a capability the agent does not have, so a skill that needs Code Interpreter on an agent without it is Setup required.
• Pinning. Pinned skills stay in every turn. Past the cap, the rest are ranked by relevance to the conversation each turn; the Prompt budget panel shows how many are in the prompt.
• Version. Each attachment follows Latest approved (vN); a skill's owner may choose Follow latest draft instead. Everyone else attaches the latest approved version.
• Approvals. Per-skill approvals (Never ask, Ask before write actions, Ask before every action) can be set per agent unless the organization policy locks them. When a referenced tool changes its schema the skill is marked Drifted and approval tightens to always until you Re-validate.
• allowed-tools. The list in SKILL.md is split and matched against the agent's tool names, so a skill can narrow what it uses but never widen it.

Use a skill in chat

Type / at the start of the message. The picker lists Skills and Saved prompts in two groups; choose one and a chip shows the skill until you send. The model can also load a skill on its own when the description matches the task (switch that off in the skill's Settings). In the answer, an activity line reads Used a skill or Used N skill steps, with invoked with /command when you chose it, and expands into the Read and Run steps with their tokens, bytes and exit codes.

Test in chat on the editor opens a chat with an agent the skill is attached to; attach it to an agent first.

Evaluate, usage and health

Evaluate

The Evaluate tab holds a trigger set: prompts that Should fire and prompts that Should not fire, one per line, plus optional Task prompts for a with/without comparison. Run evaluation sends every prompt through the live router and records which ones made the skill fire, reporting Precision and Recall, the misses, and for task prompts the tokens, steps and judge rubric with and without the skill. It may propose a Suggested description you can Apply. Evaluation runs on the draft.

Usage and health

The Usage tab shows activations over 7, 30 or 90 days, a health score, average tokens per load, the signals behind the score (Thumbs up, Thumbs down, Regenerate within the turn, Canvas edited by user within 5 min, Approval denied, Tool failed), a ledger of approvals, denials, script runs and credits, and a breakdown by agent. When the signals suggest a better description, a Suggested edit offers Open as draft.

Locales

The Locales panel lists locales/<locale>.md overlays, each carrying a translated description and body; the base SKILL.md (en) is the fallback. Translate with AI drafts the missing locales in one step.

Council skills and the run_skill node

• Council. Council skills are attached once and inherited by every seat; switch a seat off to keep a skill out of that member's turns. See the Council guide.
• Flows. The run_skill node runs a skill on a chosen agent with typed arguments bound to earlier steps. See Triggers and nodes.

Scripts

Files under scripts/ can run during a turn. Three things must be true: the organization policy allows scripts (off by default), the agent has the Code Interpreter capability, and the file is a script of the attached version. Runs are isolated from the network, stdout and stderr are capped at 32 KiB, and each run is counted in the skill's ledger. Package files download as attachments and are never rendered in the browser.

Good to know

• If the model never picks your skill: rewrite the description as the condition for using it, then run the evaluation; recall tells you whether the fix worked.
• If the agent is at its cap: This agent has reached its limit of {cap} skills; detach one, or ask an admin to raise the cap in the organization policy (up to 20).
• If you want a skill in another workspace: Export .zip and import it there; Export as plugin produces a Claude Code plugin instead.
• If you convert a prompt: the Skills page offers Convert a saved prompt to a skill; the prompt's text becomes the body and keeps working as a /command.