Skip to main content
This guide is for the operator or engineer authoring a skill — packaged instruction sets that compose into agent prompts at dispatch time. The thing you are filling in is a row in the skillDefinitions table; the thing it becomes is institutional knowledge an agent reaches for when relevant. For the conceptual frame — why skills are first-class instead of just prompt fragments — see Workforce concept. For the dispatch-time resolution flow, see Agent composition.

The three authoring paths

All three paths land in the same skill catalog, and each skill records one of five sources, shown in the table below: the platform path covers builtin and anthropic, the workspace path covers workspace, and the imported path covers marketplace and clawhub. The paths differ in mutability and provenance; the dispatch-time resolver does not care which authoring path a skill came from. You author on the workspace path; the other two bring in skills someone else wrote.

Path 1 — Platform skills (builtin and Anthropic)

Forge ships a set of skills with the platform: builtin skills (engineering conventions, safety protocols, default techniques) and anthropic skills imported from Anthropic-published plugin repositories. You do not author these. They appear in Platform > Skills on every deployment, and you assign them to agents like any other skill. Each platform skill has the same shape as one you author: a markdown body that is inlined into the agent’s system prompt, plus metadata — priority (sort order for budget trimming, lower = higher), maxInstructionTokens (per-skill ceiling), tags, and an activation mode. The platform re-syncs these skills each time a release deploys. A sync updates each skill’s content to the released version, and a platform skill that a release removes moves to deprecated.

Path 2 — Workspace (Console or API)

Use this for skills specific to your deployment — factory policies, customer-specific guidance, domain rules. In Forge Console (or with POST /api/v3/skills; see the Skills API):
  1. Navigate to Platform > Skills > Create.
  2. Fill in name, description, emoji, markdown content, tags, activation mode, priority.
  3. Submit. The skillReviewer agent runs automated quality review asynchronously.
  4. Activate when ready (draft → active).
Workspace skills are fully mutable through the Console and the API. The auto-review agent (and the operator) is the quality gate. The skillReviewer evaluates every create or update, producing a reviewStatus (unreviewed → reviewing → reviewed → validated | flagged), a numeric score, findings, suggestions, and a verdict. Admins can re-trigger a review manually from the skill detail page.

Path 3 — Imported (marketplace / ClawHub)

Use this when you want a curated third-party skill without authoring it from scratch. External catalog imports run from the Console or POST /api/v3/skill-catalog-providers/{providerId}/import:
  • Operators open Browse Skills under Platform → Skills and choose entries exposed by a catalog provider configured on their deployment. Do not assume a provider exists until it appears in that catalog.
  • Selected skills are imported with the provider’s source type (for example "clawhub"). A skill made only of reference material lands status: "active" and is usable at once. A skill that ships any script-role file lands status: "draft" and must pass automated review before it can be activated (see Skills with scripts).
  • Imported skills are immutable. The Console disables editing them, and the HTTP API refuses writes to them.
To modify an imported or platform skill, clone it to workspace (the Console button for an imported skill, or POST /api/v3/skills/{skillId}/clone for either):
  1. The clone action creates a new skill with source.type: "workspace".
  2. It copies the origin’s content, files, and metadata.
  3. It records provenance in source.clonedFrom: { skillId, importedAt }.
  4. You pick a new skillId (default suggestion: <origin>-local).
  5. The origin remains unchanged and re-importable.
This preserves upstream provenance while giving you full editing control over the local copy.

The canonical shape

Every skill, regardless of source, has the same row structure:

Skills with scripts

A skill is not limited to prose the agent reads. It can also ship executable scripts and static assets the agent runs or opens inside its sandbox. This is the determinism-ladder move: when a task has a deterministic core — a validation script, a report generator, a fixed transform — you ship that core as code instead of asking the model to re-derive it every turn. The lever is the optional fileRoles map. Each key in files gets a role that decides how the platform renders it: A files key with no matching fileRoles entry defaults to reference — so existing skills render byte-for-byte as before. Roles are additive; you only annotate the files that are scripts or assets.

The sandbox path convention

script and asset files are never inlined into the prompt. Instead, the resolver lists them by their sandbox path and — when a sandbox is available for the dispatch — materializes their bytes into the agent’s sandbox at provision time through the audited writeFiles channel. The path is deterministic:
So a skill credit-underwriting whose score.py file sits in its scripts directory (tagged script) shows up to the agent as /capabilities/skills/credit-underwriting/scripts/score.py, ready to run. The prose in content refers to that path; the model runs the script instead of reconstructing it.

A skill never provisions a sandbox

Materialization rides on a sandbox that some other part of the dispatch already provisioned — it never triggers one. If a dispatch has no sandbox (chat, a workflow node with no sandbox-backed tool), a script-bearing skill degrades gracefully rather than failing:
  • The skill’s prose instructions stay in the prompt.
  • Its scripts and assets are listed as unavailable — the agent is told the deterministic path exists but cannot be run on this dispatch.
The skill is never silently dropped. requiresCapabilities (e.g. ["sandbox"]) is the advisory signal that the skill’s scripts want a sandbox — surface it when you assign the skill, but understand it does not force provisioning.

What stays the same

Skills that ship no scripts — the overwhelming majority — behave exactly as they did before roles existed. Role-less files inline as reference, activation is unchanged, and no review gate is added. The scripts path only engages when you opt a file into the script or asset role.

Promotion loop (L2 → L3/L4)

A script that a skill ships (L2) is deterministic code, but the platform still runs it ad hoc — the agent decides each turn whether to invoke it, and there is no input contract, no test suite, and no version. When a script proves itself in production, Forge offers an advisory path to graduate it into a contracted Procedure (L3/L4). Nothing auto-promotes at any step — an operator is always in the loop. The loop has four stages:
  1. Signal (telemetry cron). A daily analyst scans sandbox execution audit rows for /capabilities/skills/<id>/<script> invocations over a trailing 7-day window. A script that crosses the stability threshold — enough invocations across enough distinct dispatches — is a promotion candidate.
  2. Advisory proposal (attention item). Each threshold-crossing script becomes a script_promotion attention item backed by a proposal row. It surfaces for an operator to review; it changes no platform behavior on its own.
  3. Operator accept → synthesis intake. When an operator accepts the proposal, Forge writes a synthesis request through the existing intake (the same path the Workflow Architect uses), tagged with the script_promotion origin. Accepting is the only trigger — the platform never accepts on the operator’s behalf.
  4. Builder lift mission. The Procedure Builder runs a lift mission: it synthesizes a contracted Procedure whose input contract is derived from the observed invocations and whose test cases come from the recorded execution samples. From there the Procedure follows the normal lifecycle — sandbox validation, provisional, then a human approval — before it is invocable at L3/L4.

Pick an activation mode

The single biggest authoring decision after the markdown itself. always — full skill content is inlined into the system prompt on every turn. The agent always has the guidance available. Cost: those tokens count against every turn’s context budget, plus the maxSkillTokens budget at compose time. on_demand — only a one-line menu entry appears in the system prompt. The agent calls the load_skill tool to load full content when needed. The platform auto-injects the load_skill tool whenever any on-demand skills are active for a dispatch. The agent sees a menu like:
The agent only spends the skill tokens on turns where it judged the skill relevant. Bulky reference material that rarely fires belongs here.

What allowedTools really does

A skill’s allowedTools field is the most-misunderstood lever in the skills system. It is not just prompt content — it is an active governance constraint enforced at the tool wrapper. Semantics:
  • A skill without allowedTools → no tool restriction from this skill.
  • A skill with allowedTools → the effective tool set is narrowed. Tools outside the set are refused at call time — the tool handler returns an error to the LLM, and a toolExecutionLog row with status refused_by_skill_constraint is written.
  • Multiple active skills with allowedTools → union of their allowed sets (permissive — any tool allowed by any active skill is usable).
A “financial protocol” skill with allowedTools: ["queryOrgChart", "queryPeople"] prevents the agent from creating tasks or modifying state while that skill is active. This turns the skill from pure prompt content into a runtime guardrail. This is why you read a skill’s content and check its allowedTools before attaching it to an agent: assigning a constrained skill to a definition narrows what the agent can do whenever that skill is active. For the resolved tool set at dispatch, see Agent composition.

Tune the budget

The platform applies a token budget to skill composition, taken from the first of these that is set:
  1. Workflow node hint: the node’s maxSkillTokens capability hint.
  2. Per-agent override: agentDefinitions.constraints.maxSkillTokens.
  3. Platform default: 32,000 tokens.
Skills are sorted by priority ascending and accumulated until the budget is reached. Overflow skills are trimmed with a resolution warning. This prevents skill-heavy agents from blowing out the system prompt. When you author a new skill, set priority thoughtfully — a critical safety skill should be priority: 0; a nice-to-have reference at priority: 100 will be the first to drop when the budget tightens.

Walk the lifecycle

Builtin and Anthropic skills move to deprecated when a release removes them and its sync runs. Workspace skills move through the lifecycle via Console actions.

Assign to agents

Skills are referenced at two levels:
  1. Agent-level permission. agentDefinitions.skills: string[] lists skill IDs the agent is permitted to use.
  2. Node-level request (workflow only). workflowGraphNodes.capabilityHints.skills: string[] lists the skills the node requests. The resolver intersects with the agent’s permitted set; unmet requests produce a warning or failure depending on the node’s skillMode.
For chat and other non-workflow dispatch sites, the agent uses its full permitted set (no per-dispatch narrowing).

What you should double-check before activating

  • The markdown is in the agent’s voice. Skills are read by the agent, not by humans. Write in second person, imperative, concrete.
  • No load-bearing facts in the description field. The description is the on-demand menu entry — keep it short and routing-focused (when should the agent load this?). Put the actual instructions in content.
  • allowedTools matches the skill’s intent. A skill that says “always confirm before publishing” but doesn’t constrain allowedTools is just a suggestion the LLM may ignore.
  • priority reflects the skill’s criticality. Don’t ship every skill at the default — the budget-trim order matters.
  • You picked the right activation mode. Check the token count. If content is over ~1,200 tokens and the skill is rarely needed, switch to on_demand.

Do it over the API

The workspace path (Path 2) has an API equivalent. These calls use the FORGE_BASE set up in the Raw HTTP tab of the quickstart. The quickstart’s ACCESS_TOKEN does not carry every scope they need, so mint it again with scope=skills:write skills:read skills:manage from an app whose roles hold them (see Requesting scopes at token mint), or send a Personal key whose scopes include them. Create the skill. The route always creates a workspace skill and ignores any other source:
This needs skills:write. Read it back to see the automated review once it has run:
This needs skills:read. Activate it when the review is acceptable:
A patch that carries status needs skills:manage as well as skills:write; without it the answer is 403 naming skills:manage and nothing is written. Changing a version-defining field mints a new immutable version, and a published workflow keeps the version it pinned. Over MCP, forge_call_operation runs the create. It is in the default start job:

See also