Skills

A skill is guidance an agent reads when it needs it: a procedure, a policy, a reference too long to keep in a state’s instructions. It is a bundle of files under skills/<slug>/, authored in an environment like a workflow: saved as a draft, published, versioned and promoted with the rest of the environment’s content.

This page covers the platform’s side: the Skills page, granting skills in the editor, and registries. How a turn discovers a skill and how skill governance resolves is the harness’s, described in Skills in the harness documentation.

Anatomy of a skill

A skill is the directory skills/<slug>/ holding a SKILL.md, plus any number of further files at any depth beneath it. Every file under the directory is part of the skill. A directory under skills/ without a SKILL.md is not a skill and is not listed.

skills/refund-policy/
  SKILL.md                    # frontmatter, then the guidance
  references/tiers.md         # read when SKILL.md points at it
skills/order-enrichment/
  SKILL.md
  scripts/fan-out.js          # run by the agent with archmax_run

SKILL.md opens with YAML frontmatter declaring name and description, followed by the body:

---
name: refund-policy
description: >-
  Decide whether a refund request qualifies and at what tier. Read this before
  approving, refusing, or disputing any refund.
---

# Refunds

1. Check the customer's tier in references/tiers.md.

The directory name is the skill’s slug, the identifier a workflow grants it by. The harness expects name to match it, and its runtime warns when they differ. The agent sees only the name and description until it decides to read the skill, so the description should name the moments that call for it.

A bundle’s scripts/ directory holds runtime scripts only: the files the agent runs with archmax_run, in a state that grants the skill. A lifecycle hook script belongs to the workflow that wires it, at workflows/<slug>/hooks/, out of the agent’s reach (see where hook scripts live).

The Skills page

Skills in the icon rail lists the skills of the environment in scope, read from its draft, so unpublished skills are listed too. The table is searchable and paginated, with one row per skill:

Column	Shows
Skill	The name from the frontmatter
Identifier	The slug, the skill’s directory name
Used by	The workflows that grant the skill, or No workflow
Files	How many files the bundle holds

The description is not a column: it is shown, in full, in the form that edits it. A skill whose frontmatter cannot be parsed is still listed, under its directory name.

Create skill is the page’s primary action, and Browse skills beside it opens the registries (see Installing from a registry). Each row ends with three actions: edit with the design agent, edit, and delete.

Creating and editing a skill

Create skill opens a form with four fields:

• Identifier: the directory name under skills/, in lowercase letters, numbers and hyphens, like refund-policy. It is fixed once created; ask the design agent to rename a skill.
• Name and Description: the frontmatter. Both are required.
• Content: the body of SKILL.md.

The platform writes skills/<identifier>/SKILL.md into the draft, and the skill is listed at once. An identifier that is already taken is refused, and the existing skill is left as it was. The edit action opens the same form, loaded from the draft, with the identifier shown but not editable. Saving rewrites SKILL.md and keeps any frontmatter key the form does not show. A SKILL.md without readable frontmatter opens with the whole file as its content. Only SKILL.md is edited here: a bundle’s reference files and scripts are written by the design agent.

Every create, edit and delete is a pending change of the environment until you publish it, and Discard in the environment’s Versioning section throws it away (see Agents and environments).

Authoring with the design agent

The row’s design agent action opens the design agent panel with a prompt in its composer naming the skill’s folder, agent/skills/<slug>/. The prompt is not sent: review it, change it, and send it yourself. The design agent can also create a skill on its own, including reference files and scripts; a skill it writes is listed as soon as its SKILL.md exists. The harness’s authoring skill, which the design agent works with, is not one of the environment’s skills and is not listed. See Design agent.

Deleting a skill

Deleting removes the whole bundle, every file under skills/<slug>/, as a pending change. The confirmation names the workflows that grant the skill. A state whose instructions mention the skill keeps mentioning it after the deletion; the platform does not rewrite instructions. Until you publish, Discard brings the skill back.

Granting a skill to a state

A skill is reachable only in the states whose lists name its slug. The lists live in workflow.yaml:

skills:
  allow_always: [order-data]        # every state of this workflow
  forbid_always: [draft-pricing]    # out of reach in every state

states:
  refund-review:
    skills:
      allow: [refund-policy]        # this state adds one
  identify-case:
    skills:
      forbid: [order-data]          # this state opts out of the workflow's grant

A forbid beats a grant at both levels. In a state that has the skill, the whole bundle is readable and its scripts are runnable; in a state that does not, the skill is refused and is not shown to the agent. The harness’s Skills guide has the full resolution rules and the validator’s reports.

In the editor the same lists are sections of the inspector:

• the workflow’s settings carry Workflow skills (skills.allow_always) and Never allowed skills (skills.forbid_always);
• each state carries Skills (skills.allow) and Forbidden skills (skills.forbid).

Add skill and Forbid a skill open a picker over the environment’s skills. A granted slug that names no skill in the environment is marked in the editor, so a renamed or deleted skill is easy to spot. The Skills page’s Used by column applies the same rule: a grant a forbid takes away does not count.

Registries

A registry is a public git repository of skill bundles, laid out as an environment’s skills are: skills/<slug>/SKILL.md. The deployment’s operator names the registries in the config’s skillRegistries list (see Config):

skillRegistries:
  - id: archmax
    title: archmax skills
    description: Skills maintained by the archmax team.
    url: https://github.com/archmax-ai/skills.git
    ref: main

Each entry has an id (a lowercase slug), a title, an optional description, an https clone url and an optional ref (default main). Without a skillRegistries key the platform follows the public archmax-ai/skills repository at main as the registry archmax; skillRegistries: [] follows none.

The platform clones each registry when it starts and brings the clone to the ref’s newest commit on every later start, in the background, so it serves requests while a clone is in progress. A registry that cannot be reached keeps serving its last clone, if there is one. A bundle holding a symbolic link or a file above the platform’s file size limit is not offered.

A registry is a source to copy from and nothing more. No turn, publish or skills listing reads it, so an environment’s skills work the same whether or not a registry is reachable.

Installing from a registry

Browse skills lists the skills of every configured registry, each with its name, its slug and its full description, with a search box. Add installs a skill: every file of its bundle is copied into the environment’s draft under skills/<slug>/, the row shows Added, and the Skills table lists the new skill. A skill whose slug the environment already holds shows as Added and offers no action; the platform never overwrites an existing skill.

When a registry could not be refreshed the dialog says so in one line, naming it. When the deployment follows no registries the dialog says This deployment follows no skill registries.

The installed copy records where it came from in its own frontmatter, under metadata, and keeps every other key and the body unchanged:

---
name: …                             # as the registry wrote it
description: …                      # as the registry wrote it
metadata:
  registry: archmax                 # the registry id
  skill: microsoft-office-documents # the slug in the registry
  commit: …                         # the commit it was copied from
---

That frontmatter is the only record of the origin. From then on the skill is an ordinary authored skill: a pending change until you publish, then edited, deleted, discarded and promoted like one you typed. Discarding before you publish removes the copy without a trace, and nothing links the copy back to the registry.