> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Author a skill

> Three ways to add a skill (built in, authored in Console, or imported), when to clone one, when to load it on demand, what allowedTools does, and how a skill ships scripts.

Last updated 2026-11-11

·
applies to 2026-11-03

·
main

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](https://docs.gloo.com/forge/concepts/workforce.md). For the dispatch-time resolution flow, see [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition).

When to reach for something else

If the instruction is a one-off — a single workflow node's prompt that won't be reused — write it inline in the node's `prompt` field. Skills are for guidance that more than one agent (or more than one node) needs. If the guidance is a fast-changing parameter (a threshold, a model name, a date) — store it in deployment config or a constants table, not a skill. Skills are markdown that the agent *reads*; they are not a config store.

***

## The three authoring paths

THREE PATHS INTO THE SKILL CATALOG

<ol aria-label="THREE PATHS INTO THE SKILL CATALOG" />

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.

| Source | Where it comes from | Mutable? | When to use |
| - | - | - | - |
| `builtin` | Ships with the Forge platform | Read-only; clone to workspace to edit | Engineering conventions, safety protocols, default techniques every deployment has |
| `anthropic` | Ships with the Forge platform, imported from an Anthropic-published plugin repository | Read-only; clone to workspace to edit | Anthropic-published skills offered on every deployment |
| `workspace` | Forge Console > Platform > Skills, or `POST /api/v3/skills` | Fully mutable | Factory policies, customer-specific guidance, domain conventions |
| `marketplace` | External catalog import | Immutable; clone to workspace to edit | Curated third-party skills (gateway-hosted) |
| `clawhub` | ClawHub catalog import | Immutable; clone to workspace to edit | Skills from the ClawHub registry |

***

## 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`.

Platform skills are read-only

The Console shows the edit action disabled on builtin and Anthropic skills, and the API refuses writes to them. To adapt one, clone it with `POST /api/v3/skills/{skillId}/clone` and edit the copy; the Console's **Clone to workspace** button appears only on imported skills. A sync never overwrites a workspace copy.

***

## 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](https://docs.gloo.com/forge/reference/http-api/skills)):

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](#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:

| Field | Purpose |
| - | - |
| `skillId` | Stable string key. UI-visible. Workflow nodes and agents reference the skill by this ID. |
| `name`, `description`, `emoji` | Display metadata. The description doubles as the on-demand menu entry. |
| `content` | The markdown body — the actual `SKILL.md` content. |
| `files` | Optional multi-file assets (`Record<string, string>`) — reference materials, templates, scripts. |
| `fileRoles` | Optional per-`files`-key role (`reference` · `script` · `asset`). Governs how each file is rendered. A key with no role defaults to `reference`. See [Skills with scripts](#skills-with-scripts). |
| `requiresCapabilities` | Optional list of capabilities the skill's scripts need at runtime (e.g. `["sandbox"]`). Advisory — a skill never *causes* a sandbox to be provisioned. |
| `skillType` | `technique` · `pattern` · `reference`. |
| `activationMode` | `always` (full content in prompt every turn) or `on_demand` (menu entry + `load_skill` tool). |
| `priority` | Sort order for token-budget trimming. Lower = higher priority. |
| `maxInstructionTokens` | Per-skill content ceiling (authoring-time discipline). |
| `allowedTools` | Governance: tools the agent may call while this skill is active. See below. |
| `tags` | Discovery metadata. |
| `source.type` | `builtin` · `anthropic` · `workspace` · `marketplace` · `clawhub`. |
| `quality` | Auto-review output: `reviewStatus`, `score`, `findings`, `suggestions`, `verdict`, `contentHash`. |
| `status` | `draft` · `active` · `deprecated` · `archived`. |

***

## 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:

| Role | Rendered as | Inlined into the prompt? |
| - | - | - |
| `reference` | Markdown appended to the skill's prompt content (today's behavior) | Yes |
| `script` | A sandbox path the agent executes | No |
| `asset` | A sandbox path the agent reads (fixtures, templates, data) | No |

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.

Where the generator puts things

Builtin skills classify by directory. Files under a skill’s scripts directory are tagged `script`; files under its assets directory are tagged `asset`; everything else stays `reference`. The skill data generator and the catalog importers apply the same prefix convention, so you rarely hand-write `fileRoles` for a builtin skill — you just put the file in the right folder.

### 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:

```text theme={null}
/capabilities/skills/<skillId>/<path>
```

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.

Script-bearing non-builtin skills need a passing review to activate

A `workspace`, `anthropic`, `marketplace`, or `clawhub` skill that carries any `script`-role file cannot move to `active` until its automated review passes — `quality.reviewStatus` must be `reviewed` or `validated`. Executable code from any source other than the Forge platform itself goes through the quality gate before an agent can run it. **Builtin skills are exempt**: their scripts ship reviewed as part of the platform release.

### 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](https://docs.gloo.com/forge/concepts/procedures.md) (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.

Advisory only

The promotion loop never changes what agents can do until an operator accepts a proposal. Detection, proposals, and the synthesis request are all observe-and-suggest — hot scripts keep running exactly as before unless and until a human promotes them.

***

## Pick an activation mode

The single biggest authoring decision after the markdown itself.

The rule of thumb

If the skill is shorter than \~1,000 tokens and is consistently relevant whenever the agent runs, use `always`. If the skill is bulky reference material the agent only needs sometimes, use `on_demand`.

**`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:

```text theme={null}
## Available On-Demand Skills
- **Underwriting Manual** (id: underwriting-manual): Load via `load_skill("underwriting-manual")` when a credit decision is required.
```

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](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-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

| Status | Resolvable? | Notes |
| - | - | - |
| `draft` | No | Default for new workspace skills. Not visible to dispatch. |
| `active` | Yes | Composed into agent prompts whenever assigned. |
| `deprecated` | Yes (with warning) | Migration window — emits a resolution warning. |
| `archived` | No | Terminal. Preserved for history. |

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](https://docs.gloo.com/forge/quickstart.md). 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](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) whose scopes include them.

Create the skill. The route always creates a workspace skill and ignores any other `source`:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/skills" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-dispute-policy-v1" \
  -d '{
    "skillId": "invoice-dispute-policy",
    "name": "Invoice dispute policy",
    "description": "Load when a vendor disputes an invoice amount.",
    "content": "# Invoice disputes\n\nConfirm the invoice number, then compare the disputed amount with the purchase order.",
    "skillType": "technique",
    "defaultActivationMode": "on_demand",
    "tags": ["finance"]
  }' \
  | jq '.data | {skillId, status, version, source}'
```

This needs `skills:write`. Read it back to see the automated review once it has run:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/skills/invoice-dispute-policy" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {status, defaultActivationMode, allowedTools, review: .quality}'
```

This needs `skills:read`. Activate it when the review is acceptable:

```bash theme={null}
curl -sS -X PATCH "$FORGE_BASE/api/v3/skills/invoice-dispute-policy" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-dispute-policy-activate-v1" \
  -d '{"status": "active"}' \
  | jq '.data | {skillId, status, version}'
```

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:

```json theme={null}
{
  "operationId": "createSkill",
  "idempotencyKey": "invoice-dispute-policy-v1",
  "input": {
    "skillId": "invoice-dispute-policy",
    "name": "Invoice dispute policy",
    "description": "Load when a vendor disputes an invoice amount.",
    "content": "# Invoice disputes\n\nConfirm the invoice number, then compare the disputed amount with the purchase order.",
    "defaultActivationMode": "on_demand"
  }
}
```

***

## See also

* [Define an agent](https://docs.gloo.com/forge/build/define-an-agent.md) — the row that *uses* the skill
* [Tool sets](https://docs.gloo.com/forge/reference/tool-sets.md) — what the skill's `allowedTools` references
* [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition) — the dispatch-time skill resolver
* [Workforce concept](https://docs.gloo.com/forge/concepts/workforce.md) — why skills are first-class
* [Tool Sets reference](https://docs.gloo.com/forge/reference/tool-sets.md) — the registry every `allowedTools` entry references


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.