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 are the part of Pioneer that turns reusable know-how into a managed runtime feature. A skill can be just instructions, but the architecture treats it as more than text: it has provenance, validation, dependencies, trust level, policy, prompt behavior, and optional tools.
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.
Why This Layer Exists
Without a skills layer, every specialized workflow would be copied into the main prompt or hardcoded into tools. That does not scale. Pioneer needs a way to install, inspect, validate, trust, enable, disable, and audit reusable 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. |
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. This lets Pioneer scan the skill directory, parse the contract, evaluate dependency preflight, verify fingerprints, and only then update 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:
---
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.
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. |
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. |
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.
_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. |
SKILL.md, but it also means native packages should avoid _meta.json unless they intentionally need compatibility override behavior.
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.tools declares dynamic tools that can be projected into the normal tool router after policy checks:
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
| 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. |
| 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. |
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:
enabled = true
allow_implicit_invocation = false
TurnStartParams.capabilities, but it is not automatically selected just because its description or path rules might match.
This is the difference between “installed” and “active.” Installed means Pioneer knows about the package. Active means this turn is allowed to use it. Implicit means Pioneer can select it automatically. Keeping those separate lets users keep powerful or experimental skills installed without letting the model discover and use 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.
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.
The design intent is that skills are not just prompt snippets. They are installable, policy-controlled, auditable runtime extensions.
Related Pages
