Skills Plane

Skills Plane

The Skills plane (s) provides agents with curated instruction sets, prompt templates, and workflow definitions. Unlike the knowledge plane (which stores documents for search), skills are structured recipes that agents load directly into their context when they need domain-specific guidance.

How It Works

Agent writes:   ?s "deployment" #devops ^3
                        ↓
Gateway:        Routes to SkillRegistry.search()
                        ↓
Registry:       Scores skills by name, tag, description, ID relevance
                        ↓
Response:       { ok: true, results: [{ id, name, description, tags, score }] }

Skills are stored as SKILL.md files with YAML frontmatter in a configurable directory. The SkillStore scans this directory, parses each file, and caches results with mtime-based invalidation — if a file hasn’t changed, it’s served from cache.

Skill Format

Each skill is a directory containing a SKILL.md file:

skills/
├── deployment/
│   └── SKILL.md          # YAML frontmatter + markdown body
├── code-review/
│   └── SKILL.md
└── testing-strategy/
    └── SKILL.md

SKILL.md Structure

---
description: "Step-by-step deployment workflow for production"
domain: development
version: 1.0.0
tags: [devops, deploy, production]
---

# Deployment Workflow

1. Run pre-deployment checks...
2. Build production bundle...
3. Deploy to staging...

Field	Source	Required
description	YAML frontmatter	Recommended
domain	YAML frontmatter (default: development)	Optional
version	YAML frontmatter (default: 1.0.0)	Optional
tags	YAML frontmatter (comma-separated or array)	Optional
name	First # heading in body (fallback: directory name)	Auto-derived
tokens	Estimated from content length (~4 chars/token)	Auto-computed

Architecture

The skills plane has 4 source files organized as a flat module at src/skills/:

File	Class	Purpose
types.ts	—	SkillDefinition, SkillSearchResult, SkillError, SkillLoadOutcome types
store.ts	SkillStore	Filesystem scanner, YAML parser, mtime cache
registry.ts	SkillRegistry	Search engine with relevance scoring and filtering
loader.ts	SkillLoader	Context injection loader with typed error codes

Data Flow

SkillStore          SkillRegistry         SkillLoader
    │                    │                     │
    ├─ loadAll()         │                     │
    │  scan directory    │                     │
    │  parse SKILL.md    │                     │
    │  cache by mtime    │                     │
    │                    ├─ search(query)       │
    │                    │  filter by tags      │
    │                    │  score matches       │
    │                    │  sort + limit        │
    │                    │                     ├─ load(id)
    │                    │                     │  returns full content
    │                    │                     │  or SKILL_NOT_FOUND

Search Scoring

The SkillRegistry scores matches on multiple dimensions:

Match Type	Score	Example
Exact name match	1.0	Query "deployment" matches skill named "deployment"
Partial name match	0.9	Query "deploy" matches "deployment workflow"
Exact tag match	0.8	Query "devops" matches tag devops
Exact ID match	0.7	Query "code-review" matches skill ID
Partial tag match	0.7	Query "dev" partially matches tag devops
Partial ID match	0.6	Query "code" partially matches ID code-review
Description match	0.5	Query appears in the skill’s description

Scores use max() — a skill matching both name and tag gets the highest single score. Results are sorted by score descending, then alphabetically for stability.

Filtering

Searches support optional filters:

// Search with tag and domain filters
registry.search("deploy", { tags: ["devops"], domain: "development" }, 5);

• Tag filter — all specified tags must be present (logical AND)
• Domain filter — exact match on domain field
• Limit — maximum results (default: 10)

CTX Operations

Operation	Example	Description
Search	?s "deployment" #devops ^3	Find skills matching query
Store	+s "new-workflow" content="..."	Register a new skill
Load	!s deployment	Load full skill content into context

Error Handling

The skills plane uses typed error codes (R2):

Code	Meaning
SKILL_NOT_FOUND	No skill with the requested ID exists
STORE_FAILED	Filesystem or parsing error in the store
PARSE_FAILED	SKILL.md file has invalid frontmatter or structure

// Load returns a typed outcome
const result = await loader.load("nonexistent");
// { ok: false, code: "SKILL_NOT_FOUND" }

Next

• Seven Planes → — the full plane architecture
• Knowledge Search → — the knowledge plane’s search system