Skills

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.

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

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

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:

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.

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

Overview

Core Systems

Subsystems

Contributing

Why this layer exists

Layers

Stable identity and skill packs

Installation

Contract shape

Supported frontmatter

Dependencies

Sidecar metadata

Runtime tool declarations

Conformance profiles

Policy

Turn resolution

Runtime tools

Audit and health

​Why this layer exists

​Layers

​Stable identity and skill packs

​Installation

​Contract shape

​Supported frontmatter

​Dependencies

​Sidecar metadata

​Runtime tool declarations

​Conformance profiles

​Policy

​Turn resolution

​Runtime tools

​Audit and health

​Related pages

Why this layer exists

Layers

Stable identity and skill packs

Installation

Contract shape

Supported frontmatter

Dependencies

Sidecar metadata

Runtime tool declarations

Conformance profiles

Policy

Turn resolution

Runtime tools

Audit and health

Related pages