Give your work a Skill

A Skill teaches devboxes' agent how your team does one thing: how to work with an external system or tool, or the format a kind of work delivers. It is a folder in the Agent Skills format: a SKILL.md with a name, a description and instructions in Markdown, and optional files beside it, such as scripts and references. Facts about your Organization belong in Organization memory instead.

Any member, and anyone in a Chat thread, writes Skill drafts. Only owners and admins commit a draft, and only a committed version reaches work. A Skill is versioned like a Blueprint: each change is a draft with a diff against the live version.

Ask in Chat

Tell devboxes how your team uses a tool, in a channel where it works:

@devboxes for anything that touches our dashboards: Grafana is at grafana.tools.internal, filter every panel by the env variable, and never edit the shared Production overview board, copy it first.

devboxes writes a Skill draft, tags it with a fitting tag your Organization already uses, and shows it in the thread. An owner or admin commits it by approving it there.

Create a Skill by name

On the Skills page, choose New Skill and enter its name: lowercase letters and digits, with single hyphens between them, at most 64 characters, such as release-notes. devboxes creates the Skill with an empty first draft and opens the draft. From the CLI:

create.json

{
  "organizationId": "<organization id>",
  "name": "release-notes"
}

devboxes invoke skills.create --input @create.json

Write the draft with skills.replace-draft, then commit it. Both take the draft's revision, which is 0 for a new draft. When someone wrote the draft again after you read it, the write or the commit fails with SKILL_DRAFT_CHANGED and the draft stays as it is. Read it again with catalogue.get, and start from what it holds now.

Import a Skill from GitHub

On the Skills page, paste the GitHub address of a folder that holds a SKILL.md and choose Import. From the CLI:

import.json

{
  "organizationId": "<organization id>",
  "address": "https://github.com/<owner>/<repository>/tree/main/skills/release-notes"
}

devboxes invoke skills.import --input @import.json

The address names a folder at a branch, tag or commit, that folder's SKILL.md, or a repository whose top folder holds SKILL.md. A ref with a slash, such as release/1.2, can't be named. The SKILL.md must state the Skill's name. The import creates the Skill and its first draft, untagged. When a Skill of the same name exists, the import becomes its new draft and keeps its tags and its Always include setting. A private repository needs the Organization's GitHub App installed on its owner.

Choose which work loads it

A Run loads the latest committed version of every Skill that shares a tag with the Run's Blueprint version or its Project. A tag is a domain word such as frontend, security or marketing. A Skill without tags loads nowhere.

Where the tag goes	How
A Skill	The draft's tags on its version page, or `tags` in `skills.replace-draft`.
A Project	The Project's General page under Settings > Projects, `tags` in `projects.configure`, or an owner or admin asking devboxes in Chat.
A Blueprint	`tags` in `blueprints.replace-draft`, committed with the Blueprint's next version.

The agent loads a tagged Skill when the work fits it. Turn on Always include only for a format that all work follows: that Skill loads into every Run, in full, in the Run's first prompt. Chat replies load no Skills.

Commit, discard and archive

An owner or admin commits a draft from its version page, or approves it in the Chat thread that showed it. Any member discards a draft they don't need, and archives a Skill to stop loading it. The Skills page's Archived list shows the archived Skills, and a Skill's version page restores it. The operations are listed under Skills.