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

# Skills

> Skill installation, validation, policy, prompt resolution, and runtime tools.

Skills are installed instruction/tool packages compatible with the Agent Skills style of `SKILL.md` packages. Pioneer parses the skill contract, validates it, installs it into managed roots, resolves active skills per turn, and can expose skill runtime tools to the model.

Skills turn reusable instructions into a managed runtime feature. A skill can contain only instructions, but Pioneer also tracks its provenance, validation, dependencies, trust level, policy, prompt behavior, and optional tools.

<Note>
  Skills and MCP both add capabilities to the agent, but they solve different problems. Skills package instructions and optional runtime tools. MCP connects Pioneer to external tool servers. Both eventually materialize through the tool runtime when they expose callable tools.
</Note>

## Why this layer exists

Without a skills layer, specialized workflows would be copied into the main prompt or hardcoded into tools. Pioneer instead provides a lifecycle for installing, inspecting, validating, trusting, enabling, disabling, and auditing capability packages.

The skills layer keeps that lifecycle out of the agent loop. The agent only needs resolved skills for the current turn and dynamic tools that passed policy. Installation, upload, dependency checks, security scans, catalog loading, and trust decisions happen before the agent sees anything.

## Layers

| Layer           | Code                      | Responsibility                                                                                                                |
| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Contract parser | `skills/src/contract.rs`  | Reads `SKILL.md`, YAML frontmatter, sidecar metadata, dependencies, allowed tools, path rules, and runtime tool declarations. |
| Installer       | `skills/src/installer.rs` | Stages source, scans security, checks dependencies, writes lock entries, installs, updates, and uninstalls.                   |
| Catalog         | `skills/src/catalog.rs`   | Loads installed skills into catalog snapshots.                                                                                |
| Policy          | `skills/src/policy.rs`    | Merges gateway and workspace policy into effective enabled and implicit-invocation flags.                                     |
| Resolver        | `skills/src/resolver.rs`  | Chooses which skills are active for a turn.                                                                                   |
| Prompt builder  | `skills/src/prompt.rs`    | Builds the `[Skills]` dynamic prompt section.                                                                                 |
| Runtime tools   | `skills/src/runtime.rs`   | Validates and materializes dynamic tool declarations.                                                                         |

## Stable identity and skill packs

The catalog treats a skill's stable `SkillId` as its identity, separate from its display name, source path, or current pack membership. A skill can then be renamed, moved between sources, or transferred to another owner without losing installed policies, bindings, or history. The installer backfills identity for older records before normal lifecycle operations continue.

A skill pack is an installation and lifecycle boundary for multiple skills. Pack install, update, and uninstall are coordinated as atomic operations. The catalog projects pack membership while preserving the identity and policy of retained members; removed members are removed deliberately rather than being silently replaced by same-named skills from the new source. The composer can resolve a complete pack or an individual member into explicit turn capabilities.

## Installation

The gateway handles install/update/uninstall requests under `message/skills`. Uploaded archives use an upload session protocol: start upload, send chunks, finish, then install from the materialized archive. The upload path enforces size, chunk, archive entry, and cleanup limits.

The installer stages source before committing it. Pioneer scans the skill directory, parses the contract, evaluates dependency preflight, verifies fingerprints, and then updates the installed skill root and lock file.

## Contract shape

A skill source is a directory whose root contains `SKILL.md`. Uploaded archives must materialize to one top-level directory, and that directory must contain `SKILL.md`. The installer rejects absolute paths, parent traversal, duplicate archive paths, unsupported archive entries, symlinks in copied sources, and files that exceed configured size limits.

`SKILL.md` has YAML frontmatter followed by a non-empty Markdown body:

```md theme={null}
---
name: repo-review
slug: repo-review
description: Review code using the team's checklist. Use when the user asks for a code review or release-readiness pass.
allowed-tools: Read Bash(git:*)
dependencies:
  bins:
    - git
---

# Repo review

Read `references/checklist.md` before reviewing code.
```

Pioneer parses an Agent Skills-compatible contract plus Pioneer runtime extensions. For native Pioneer skills, identity and behavior fields belong in `SKILL.md` YAML frontmatter. `_meta.json` is a compatibility sidecar for imported OpenClaw-style or registry-style packages, not the preferred native authoring format.

At parse time, `SKILL.md` must exist, the body must not be empty, and the skill must have a `slug`. Native packages should provide that slug in frontmatter. Imported compatibility packages may provide it through `_meta.json`. Agent Skills strict conformance also requires `name` and `description`; Pioneer can still parse fallback values, but validation will report strict conformance issues.

### Supported frontmatter

| Field                      | Status                                         | Type                         | Default / precedence                                                                                  | Semantics                                                                                                                |
| -------------------------- | ---------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name`                     | Native required by convention; strict-required | string                       | `_meta.json.displayName`, then `slug` if frontmatter is missing                                       | Human-facing name. Native skills should set it in frontmatter.                                                           |
| `slug`                     | Required to parse                              | string                       | `_meta.json.slug` overrides frontmatter                                                               | Normalized to lowercase hyphen form and stored with owner as `owner/slug`.                                               |
| `owner`                    | Optional                                       | string                       | `_meta.json.owner` or `_meta.json.ownerId`, then frontmatter, then nested source path, then `pioneer` | Namespace for the qualified slug.                                                                                        |
| `description`              | Native required by convention; strict-required | string                       | First non-empty body line if missing                                                                  | Skill summary and trigger description.                                                                                   |
| `license`                  | Optional                                       | string                       | None                                                                                                  | Optional license string.                                                                                                 |
| `compatibility`            | Optional                                       | string                       | None                                                                                                  | Optional compatibility note. Strict profile requires 1..=500 characters when provided.                                   |
| `version`                  | Optional                                       | string                       | `_meta.json.version`, then `_meta.json.latest.version`, then frontmatter                              | Version hint. Native skills should set it in frontmatter.                                                                |
| `user-invocable`           | Optional                                       | boolean                      | `true`                                                                                                | Controls whether the skill can be selected explicitly.                                                                   |
| `disable-model-invocation` | Optional                                       | boolean                      | `false`                                                                                               | Prevents automatic model-side invocation when set.                                                                       |
| `paths`                    | Optional                                       | string or list of strings    | Empty list                                                                                            | Path match rules used by the resolver.                                                                                   |
| `allowed-tools`            | Optional                                       | string or list of strings    | Empty list                                                                                            | Agent Skills tool allowlist hint. Pioneer accepts both forms, but strict Agent Skills requires a space-separated string. |
| `dependencies`             | Optional                                       | object                       | Empty dependency set                                                                                  | Dependency checks for environment variables, binaries, commands, config keys, MCP servers, and API keys.                 |
| `metadata`                 | Optional                                       | object or JSON-object string | `{}`                                                                                                  | Raw metadata retained in the compiled definition. Pioneer recognizes `openclaw` and `clawdbot` namespaces.               |
| `runtime`                  | Optional                                       | object                       | No runtime tools                                                                                      | Dynamic runtime tool declarations.                                                                                       |

Unknown frontmatter keys are ignored by the parser unless they are inside a typed section such as `runtime.tools.output_policy`, where serde validation rejects unknown policy fields.

### Dependencies

The `dependencies` object supports these lists:

| Field      | Status   | Type                   | Checked today                 | Meaning                                                                 |
| ---------- | -------- | ---------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `env`      | Optional | string or string array | Yes                           | Environment variables that must be set and non-empty.                   |
| `api_keys` | Optional | string or string array | Yes                           | API key environment variables that must be set and non-empty.           |
| `bins`     | Optional | string or string array | Yes                           | Executables that must be available in `PATH`.                           |
| `commands` | Optional | string or string array | Yes                           | Command dependencies that must be available in `PATH`.                  |
| `mcp`      | Optional | string or string array | Yes                           | MCP server names that must be registered in the dependency check input. |
| `config`   | Optional | string or string array | Stored, not baseline-enforced | Config dependencies retained in the compiled definition.                |

The compiler also merges known dependency metadata from `metadata.openclaw.requires` and `metadata.clawdbot.requires` into the normalized dependency set.

Dependencies are readiness checks, not installation instructions. The dependency evaluator checks the current gateway environment and reports missing or blocked requirements; it does not install binaries or commands. If a skill body contains setup instructions that install a command, do not declare that command as a required dependency unless the command must already exist before the skill can be installed or used.

### Sidecar metadata

`_meta.json` support exists for compatibility with imported OpenClaw-style or registry-style skill packages. Native Pioneer skills should put contract data in `SKILL.md` YAML frontmatter instead.

If `_meta.json` exists beside `SKILL.md`, Pioneer reads only these fields:

| Field                | Semantics                                                 |
| -------------------- | --------------------------------------------------------- |
| `owner` or `ownerId` | Owner namespace override.                                 |
| `slug`               | Slug override.                                            |
| `version`            | Version hint override.                                    |
| `latest.version`     | Fallback version hint.                                    |
| `displayName`        | Fallback display name when frontmatter `name` is missing. |

Sidecar identity fields take precedence over frontmatter identity fields. Imported registry metadata can therefore stabilize package identity without rewriting `SKILL.md`. Native packages should avoid `_meta.json` unless they intentionally need compatibility overrides.

Pioneer does not read `description`, `dependencies`, `paths`, `allowed-tools`, `metadata`, `user-invocable`, `disable-model-invocation`, or `runtime` from `_meta.json`; those fields are frontmatter-only.

### Runtime tool declarations

`runtime.tools` declares dynamic tools that can be projected into the normal tool router after policy checks:

```yaml theme={null}
runtime:
  tools:
    - tool_slug: run-report
      description: Run the report helper.
      kind: shell
      parameters:
        type: object
        additionalProperties: false
      execution_class: exclusive
      config:
        command:
          - scripts/run-report.sh
      output_policy:
        llm:
          mode: summary_only
```

Each tool has:

| Field             | Status   | Type                                       | Default                      | Semantics                                                                                                                                                                                             |
| ----------------- | -------- | ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool_slug`       | Required | string                                     | None                         | Normalized to lowercase hyphen form. Canonical name becomes `skill.<normalized-skill>.<normalized-tool>`.                                                                                             |
| `description`     | Optional | string                                     | `Runtime tool '<tool_slug>'` | Tool description.                                                                                                                                                                                     |
| `kind`            | Required | `shell`, `http`, or `function_proxy`       | None                         | Runtime class.                                                                                                                                                                                        |
| `parameters`      | Optional | JSON schema object                         | Open object                  | Function-call argument schema.                                                                                                                                                                        |
| `execution_class` | Optional | `shared`, `exclusive`, or `session_scoped` | `shared`                     | Scheduling hint for the tool router.                                                                                                                                                                  |
| `config`          | Optional | object                                     | `{}`                         | Kind-specific configuration. Shell tools read `config.command`; HTTP tools read request defaults such as `url`, `method`, `headers`, and `timeout_ms`; function proxies require `config.target_tool`. |
| `output_policy`   | Optional | object                                     | Host default                 | Dynamic output policy request. Host caps may narrow or reject it.                                                                                                                                     |

Runtime tool declarations are not enough to expose a tool. The runtime planner also checks dynamic-tool enablement, allowed tool kinds, trust thresholds, duplicate canonical names, max tools per skill, dependency health, and output policy constraints.

### Conformance profiles

Pioneer produces a conformance report with two profiles:

| Profile              | Purpose                                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentskills_strict` | Checks the open Agent Skills shape: `name`, `description`, name length and hyphen rules, strict `allowed-tools` string form, and strict metadata value types. |
| `openclaw_compat`    | Checks OpenClaw-style `name`, `description`, and recognized `metadata.openclaw` / `metadata.clawdbot` shapes.                                                 |

Conformance issues are stored on `SkillDefinition`. Resolver policy decides whether validation issues block activation.

The compiler turns parsed data into a `SkillDefinition` with identity, instructions, source information, trust level, dependencies, runtime tools, metadata, conformance report, and fingerprint.

## Policy

Effective skill policy starts with:

```text theme={null}
enabled = true
allow_implicit_invocation = false
```

Gateway policy can override those values, and workspace policy can override gateway policy. A disabled skill remains installed but does not participate in turn resolution. A non-implicit skill can still be used when explicitly invoked, including through `TurnStartParams.capabilities`, but it is not automatically selected just because its description or path rules might match.

"Installed" and "active" have different meanings. Installed means Pioneer knows about the package. Active means the current turn may use it. Implicit means Pioneer may select it automatically. Keeping these states separate lets users store powerful or experimental skills without exposing them silently.

## Turn resolution

At turn time, the agent resolves skills using installed catalog data, workspace policy, explicit composer capabilities, path matches, explicit textual references, and implicit invocation rules. Composer-selected skills are normalized into explicit skill refs and resolved with reason `ExplicitCapability`, persisted as `explicit_composer_capability` in turn skill bindings.

The dynamic skills prompt starts compactly: display name, exact `read_skill` slug, and "use when" description. Composer-selected skills stay compact and do not inject full skill bodies. Full bodies are eligible only for path-matched skills when the prompt budget allows. Otherwise the model is told to call `read_skill` with the exact slug.

Missing, disabled, dependency-blocked, validation-rejected, or security-blocked composer skills are reported as rejected turn capabilities. The user message can still show the requested chip for auditability, while capability diagnostics explain what was actually accepted or rejected.

## Runtime tools

Skills can declare runtime tools. Pioneer validates their declarations and output policies before exposing them. Runtime tools can be shell, HTTP, or function-proxy style tools. Trust policy can require higher trust for more dangerous runtime classes.

When a skill tool is accepted, including from a composer-selected skill, the agent materializes it into a `ToolExtensionBundle` and adds it to the same tool router as built-in, MCP, and task tools. If policy narrows an output declaration or excludes a tool, the agent logs diagnostics and continues the turn.

## Audit and health

Skill operations produce audit events. Turn-time resolution can also store dependency diagnostics. Health APIs report validation issues, dependency status, security findings, policy state, and whether the installed skill can be safely used.

Skills are installable runtime extensions. The gateway controls their policy and records their use.

## Related pages

* [Creating Skills](/skills/creating) gives the user-facing package authoring flow.
* [Prompt And Context](/architecture/prompt) explains how resolved skills become the `[Skills]` prompt section.
* [Tools System](/architecture/tools) explains how skill runtime tools are routed and projected.
* [MCP Architecture](/architecture/mcp) explains the external-server extension path.
* [Persistence Layer](/architecture/persistence) explains skill installations, policies, bindings, audits, and dependency snapshots.