Author a Skill

Your team has procedures that work best when they always run the same way. AP reconciles a payment. Operations classifies an inbound ticket. Manufacturing validates a quality report against tolerance. A Skill packages one of those procedures into something the agent can call by name.

You author a small folder of markdown and supporting files. The platform makes the Skill available to anyone with the right scope. Every reference picks up the same logic, so the procedure runs the same way every time.

Audience: builders

The model

Every Skill is a folder with one canonical file, SKILL.md, plus any supporting assets. SKILL.md has a YAML frontmatter block and a markdown body.

The frontmatter has three required fields and one optional field:

name. What teammates see in the picker.
description. One sentence on what the Skill does.
when_to_use. A list of trigger phrases that tell the agent when this Skill applies. Required: a Skill without when_to_use will not finalize.
icon. Optional. A registry key, emoji, or asset path.

The body is the operating guide the agent reads when it decides to call the Skill. Write it the way you would brief a new analyst: the steps, the constraints, the examples.

when_to_use is the discovery contract. The agent matches your trigger phrases against the user's prompt to decide whether to call this Skill. Vague triggers ("when relevant") never fire. Concrete triggers ("when the user asks for a vendor exception summary") do.

Scaffold a draft

Skill drafts live inside a Project. Scaffold the draft, edit the files in place, then finalize it to make it callable.

Open a Project's Context tab and pick Skills

In the section header, click Skill. The create dialog asks for a name, an optional slug, and the owner scope: Personal, Project, Team, or Workspace. Scope determines who can see and call the Skill once finalized.

Create the starter

The platform writes SKILL.md to a draft path under .blockparty/skill-drafts/<scope>/<id>/<slug>/. The starter has the frontmatter shape filled in with placeholders and a single Instructions section.

Edit in place

Use the file editor on the draft path. Add supporting files (examples, prompt snippets, reference markdown) to the same folder. The draft is just files in your Project volume.

Finalize the draft

A draft is private until you finalize it. Finalize compiles the draft into a registered Skill that shows up in @-mention pickers and the workspace catalog.

Drafts must be finalized to appear in @-mention pickers. Writing files at <draft>/SKILL.md only persists a draft on disk. Until you finalize, the agent cannot find the Skill by name.

Click Publish on the draft. The platform validates the frontmatter and routes the outcome:

Published. You had permission for the chosen scope. The Skill is live.
Proposal submitted. A team or workspace Skill from a non-admin queues for review.
Blocked. A required field is missing or you do not have permission. Read the validation error and fix the draft.

Import a `.skill` archive

Drop a .skill archive (a zip with a SKILL.md at its root) into the Skills section. The platform unpacks it, normalizes the frontmatter, and creates a draft.

If the archive was authored elsewhere and is missing when_to_use, the importer synthesizes a placeholder so finalize does not fail. A banner names the synthesized field. Edit it to something specific before relying on the Skill.

The importer enforces a 50 MB total and 500 file limit per archive, and it strips junk files (.DS_Store, __MACOSX/, and similar).

Publish workspace-wide

To make a Skill available to every Project in the workspace, set the scope to Workspace when you scaffold (or when you import). Workspace publishes from non-admins file as proposals for a workspace admin to approve.

Team-scoped Skills work the same way for the active team's admins.

Where Skills are stored

Drafts live at .blockparty/skill-drafts/<scope>/<id>/<slug>/ in the Project volume. Published Skills live at .blockparty/skills/<scope>/<slug>/ plus a snapshot row in the workspace catalog. The snapshot is the canonical source: built-in and workspace Skills both surface their SKILL.md from the snapshot, with the volume read as a fallback.