Skills System

This page is in two sections. Read the one you need.

• How-To: Write and deploy a custom skill — if you want to create a skill for your domain
• Reference: Skills system specification — if you need to look up the skill format, scoring algorithm, or built-in skill catalog

How-To: Write and Deploy a Custom Skill

This section is a How-to guide. You are a competent user with a specific goal: adding a new skill to VECTOR. Steps are direct and assume you understand the system basics.

How to Create a Skill File

Create a new markdown file in the skills/ directory at the workspace root:

touch ~/.openclaw/workspace/skills/my-skill.md

The skill router picks it up automatically on next PM spawn. No registration needed.

How to Structure Your Skill

A skill must contain these sections to be matched and injected correctly:

# Skill Name

## When to Use
- Specific scenario where this skill applies
- Another scenario

## NOT For
- Out-of-scope use case (prevents false-positive matching)

## Context Injection Points
1. `config-file.yaml` → what data to load from it
2. `SOUL.md` → how identity affects this skill's output

## Procedure

### Step 1: [Name of step]
1. **Action**: The specific thing to do
2. **Verify**: How to confirm it worked
3. **Fallback**: What to do if the verify step fails

### Step 2: [Name of step]
[Same pattern]

## Hard Blocks
- NEVER do X in this domain
- NEVER skip Y

## Soft Checks
- Prefer A over B
- Warn if C condition is detected

## Quality Metrics
| Metric | Target | How to Measure |
|--------|--------|----------------|
| Success rate | > 95% | Track outcomes per use |

## Learning Hooks
- Log: what worked, failure modes, time to complete, Chief feedback

The When to Use and NOT For sections drive semantic matching. Write them precisely — vague phrasing means poor match scores.

How to Target a Skill to a Specific PM

By default, the router scores a skill against any PM spawn. To restrict a skill to specific PMs, add a Scope block:

## Scope
- PM: FORGE, SENTINEL
- Domain: engineering

A scoped skill will only be injected into matching PM types. SAGE spawns will never see a skill scoped to FORGE.

How to Compose Skills (Skill Grafting)

When your skill depends on another skill's output, declare the dependency:

## Dependencies
- `research-pipeline` — this skill expects research to be completed first
- `design-system` — this skill outputs content that follows brand rules

## Exports
- `compiled_brief` — structured output other skills can consume

When the router matches your skill, it also injects declared dependencies automatically. The PM receives the full chain.

How to Use Customer-Specific Context

For enterprise deployments where each customer has their own brand or compliance rules, place customer context files in a customer-named directory:

customers/
  acme-corp/
    brand.yaml       # Colors, fonts, voice rules
    compliance.yaml  # Regulatory constraints
    voice-rules.md   # Writing standards specific to Acme

Inject the customer directory as context in the task spec:

Task: Write a LinkedIn post for Acme Corp's product launch.
Customer context: customers/acme-corp/

The skill router loads brand.yaml and compliance.yaml from the customer directory instead of the defaults. The same skill produces Acme-appropriate output without any skill modification.

How to Test a New Skill

Before deploying a skill to production tasks, test it in isolation:

# Check that the skill file is valid markdown
node scripts/validate-skill.js skills/my-skill.md

# Run the router against a sample task to see if your skill matches
node scripts/skill-router.js --task "your sample task description" --preview

The preview mode shows match scores without spawning a PM. Adjust your When to Use section until the score is above 0.7 for tasks you expect to match.

Reference: Skills System Specification

This section is a Reference. It describes the skills machinery. Consult it when you need a specific fact about format, scoring, or available skills.

Skill File Location

The router scans all .md files in skills/ recursively on each PM spawn.

Matching Algorithm

Skills are scored against the PM spawn context using semantic similarity. Scoring factors:

Thresholds:

Maximum injected skills per PM spawn: 5. If more than 5 skills score above 0.70, the top 5 by score are injected.

Required Skill Sections

Standard Context Files

Fallback brand values (when brand.yaml is absent):

Built-In Skill Catalog

Injection Format in PM Context

When a skill is injected, it appears in the PM's boot context as:

🔧 Relevant Skills (auto-matched):

### design-system (score: 0.78)
[Full skill content]

### content-publishing (score: 0.77)
[Full skill content]

The PM reads these at boot, before any task work begins.

Skill Validation Rules