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 coversbuiltin 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 withPOST /api/v3/skills; see the Skills API):
- Navigate to Platform > Skills > Create.
- Fill in name, description, emoji, markdown content, tags, activation mode, priority.
- Submit. The
skillRevieweragent runs automated quality review asynchronously. - Activate when ready (
draft → active).
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 orPOST /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 landsstatus: "active"and is usable at once. A skill that ships anyscript-role file landsstatus: "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.
POST /api/v3/skills/{skillId}/clone for either):
- The clone action creates a new skill with
source.type: "workspace". - It copies the origin’s
content,files, and metadata. - It records provenance in
source.clonedFrom: { skillId, importedAt }. - You pick a new
skillId(default suggestion:<origin>-local). - The origin remains unchanged and re-importable.
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 optionalfileRoles 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:
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.
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-lessfiles 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:- 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. - Advisory proposal (attention item). Each threshold-crossing script becomes a
script_promotionattention item backed by a proposal row. It surfaces for an operator to review; it changes no platform behavior on its own. - 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_promotionorigin. Accepting is the only trigger — the platform never accepts on the operator’s behalf. - 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:
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 atoolExecutionLogrow with statusrefused_by_skill_constraintis written. - Multiple active skills with
allowedTools→ union of their allowed sets (permissive — any tool allowed by any active skill is usable).
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:- Workflow node hint: the node’s
maxSkillTokenscapability hint. - Per-agent override:
agentDefinitions.constraints.maxSkillTokens. - Platform default: 32,000 tokens.
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:- Agent-level permission.
agentDefinitions.skills: string[]lists skill IDs the agent is permitted to use. - 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’sskillMode.
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. allowedToolsmatches the skill’s intent. A skill that says “always confirm before publishing” but doesn’t constrainallowedToolsis just a suggestion the LLM may ignore.priorityreflects 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
contentis over ~1,200 tokens and the skill is rarely needed, switch toon_demand.
Do it over the API
The workspace path (Path 2) has an API equivalent. These calls use theFORGE_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:
skills:write. Read it back to see the automated review once it has run:
skills:read. Activate it when the review is acceptable:
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
- Define an agent — the row that uses the skill
- Tool sets — what the skill’s
allowedToolsreferences - Agent composition — the dispatch-time skill resolver
- Workforce concept — why skills are first-class
- Tool Sets reference — the registry every
allowedToolsentry references

