Skills System

Skills System

Skills are codified expertise — reusable procedural patterns that bridge reasoning and action. They represent Tier 4 (Procedural Memory) in CortexPrism's 5-tier memory architecture.

Skills can be human-authored (TypeScript modules or markdown files) or LLM-learned (automatically extracted from successful agent tool-call sequences).

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Skills System                            │
│                                                               │
│  Sources               Storage             Retrieval          │
│  ┌──────────┐     ┌──────────────┐    ┌──────────────────┐  │
│  │ Built-in  │────▶│              │    │ Embedding-based   │  │
│  │ (TS)      │     │ procedural_  │◀───│ (cosine similarity)│  │
│  ├──────────┤     │ memory table  │    │ + lexical fallback │  │
│  │ Filesystem│────▶│ (memory.db)   │    │ + quality ranking  │  │
│  │ (.md)     │     │              │    └──────────────────┘  │
│  ├──────────┤     │ 17 columns    │            │              │
│  │ LLM-learned│───▶│ 8 indexes     │            ▼              │
│  │ (sessions)│     └──────────────┘    ┌──────────────────┐  │
│  └──────────┘                          │ Agent System      │  │
│                                        │ Prompt Injection   │  │
│  Management                            │ + Tools            │  │
│  ┌──────────────────────┐             └──────────────────┘  │
│  │ Lifecycle (6 states)  │                                     │
│  │ Health (4 signals)    │                                     │
│  │ Deduplication         │                                     │
│  │ Dependency graph      │                                     │
│  │ Trust tiers (1-4)     │                                     │
│  └──────────────────────┘                                     │
└──────────────────────────────────────────────────────────────┘

---

Skill Sources

1. Built-in Skills

12 skills in src/skills/builtin/, registered in BUILTIN_SKILLS array. Loaded on startup via registerBuiltinSkills(). Default: lifecycle: 'released', trust_tier: 4.

Category	Skills
Agent Reasoning	plan-complex-tasks, handle-failure-recovery, reflect-on-outcomes
Memory & Learning	use-episodic-memory, extract-semantic-knowledge, learn-procedural-skills
System Operations	diagnose-agent-failures, profile-performance, analyze-errors
Development	design-tool-interface, test-code-reliability, implement-database-changes

2. Filesystem Skills

Create .cortex/skills/<name>/SKILL.md with YAML frontmatter:

---
name: my-skill
description: What this skill does
trigger_pattern: optional trigger phrase
---

# My Skill

## Steps
1. **Step one** — use tool_name
2. **Step two** — verify with another_tool

Loaded via loadHumanSkills() or Web UI "Load .cortex/skills" button.

3. LLM-Learned Skills

Automatically extracted from tool-call sequences during sessions (≥2 tool calls per turn). Stored with origin: 'llm', lifecycle: 'candidate', trust_tier: 1. Auto-deduplicated against existing skills.

---

Data Model

interface Skill {
  id: string;                   // Unique ID
  name: string;                 // snake_case unique identifier
  description: string | null;    // One-sentence description
  trigger_pattern: string | null; // Matching phrases
  steps: string;                // JSON SkillStep[]
  success_rate: number;         // Bayesian rolling average (0.0-1.0)
  invocation_count: number;
  version: number;              // Auto-incremented on change
  source_session: string | null;
  origin: 'human' | 'llm';
  content: string | null;       // Full markdown instructions
  created_at: string;

  // v0.36.0+ enhancements
  lifecycle: 'candidate' | 'verified' | 'released' | 'degraded' | 'deprecated' | 'archived';
  parent_skill_id: string | null;
  trust_tier: number;           // 1-4
  utility_score: number;
  freshness: number;            // 0.0-1.0 time-decay
  token_cost: number;
  last_used_at: string | null;
  last_validated_at: string | null;
  deprecated_reason: string | null;
  depends_on: string | null;    // JSON array of skill names
  conflicts_with: string | null;
  embedding: Uint8Array | null;
  embedding_model: string | null;
  metadata?: SkillMetadata | null;
}

interface SkillStep {
  step: number;
  action: string;
  description: string;
  tool?: string;
  params?: Record<string, unknown>;
}

---

Lifecycle

candidate → verified → released → degraded → deprecated → archived

State	Default for	Description
candidate	LLM-extracted	New, untested
verified	Promoted	Reviewed, proven
released	Human-authored, built-in	Actively available
degraded	Low health score	Quality slipping
deprecated	Stale/low-quality	No longer recommended
archived	Merged	Retired, excluded

Deprecated and archived skills are excluded from all retrieval and agent prompts.

---

Retrieval & Matching

Embedding-Based (Primary)

When an EmbeddingProvider is available:

1. User query is embedded
2. Top-100 skills with precomputed embeddings loaded
3. Cosine similarity computed, threshold: 0.3
4. Ranked by similarity × quality score
5. Gaps filled from lexical fallback

Lexical (Fallback)

• Words ≥4 chars matched via LIKE %word% against name, description, trigger_pattern
• Ranked by utility_score DESC, success_rate DESC

Reliability Filtering

filterReliableSkills() gates agent exposure:

• Human-authored: always pass
• LLM at released/verified lifecycle: pass
• LLM at trust_tier ≥ 2 + success_rate ≥ 0.3: pass
• Otherwise: requires success_rate ≥ 0.5

---

Quality & Health

Quality Signals

Signal	Description
success_rate	Bayesian rolling average
utility_score	+0.1 on success, −0.05 on failure
freshness	1.0 − (days_since_last_use / 30), min 0.05
token_cost	Avg tokens per invocation

Health Score

overall = utility × 0.35 + (1 − redundancy) × 0.25 + freshness × 0.20 + (1 − failureRisk) × 0.20

Auto-Maintenance

runSkillHealthMaintenance() deprecates stale/low-quality LLM skills based on freshness and overall health score. Triggered from Web UI or API.

---

Deduplication & Merging

• findSimilarSkills() detects duplicates via embedding similarity (threshold: 0.75) or lexical matching
• mergeSkill() combines steps, descriptions, content; archives source; bumps version
• deduplicateExtractedSkill() auto-runs after every LLM extraction

---

Trust Tiering

Tier	Default for	Agent Exposure
1	LLM-extracted	success_rate ≥ 0.5 only
2	LLM (verified, 30%+)	success_rate ≥ 0.3
3	Human-authored	Always
4	Built-in	Always, marked ★

---

Dependency Tracking

Skills declare depends_on and conflicts_with as JSON arrays of skill names.

• deleteSkill() blocks if dependent skills exist
• getSkillDependents() / getSkillDependencies() query the graph
• skill_write tool exposes dependents and dependencies operations

---

Agent Tools

Tool	Description
load_skill(name)	Load full instructions + lifecycle + quality
skill_read(name?, origin?, lifecycle?, limit?)	List/inspect skills
skill_write(operation, name, ...)	8 operations: create, update, delete, merge, promote, deprecate, dependents, dependencies

---

REST API

Method	Endpoint	Description
GET	/api/skills	List (filter: ?origin=, ?lifecycle=)
GET	/api/skills/stats	Stats with new metrics
GET	/api/skills/detail?name=	Single skill
POST	/api/skills	Create human skill
DELETE	/api/skills?name=	Delete (blocked if dependents exist)
POST	/api/skills/merge	Merge { target, source }
POST	/api/skills/deprecate	Deprecate { name, reason }
POST	/api/skills/promote	Promote { name }
POST	/api/skills/load-human	Load from .cortex/skills/
POST	/api/skills/export	Export to filesystem
GET	/api/skills/dependencies?name=	Dependency graph
GET	/api/skills/health?name=	Health report / run maintenance

---

Web UI

The Skills page provides:

• Stats bar with utility, freshness, active/deprecated counts
• Lifecycle badges (color-coded) and trust tier stars (★☆☆☆ to ★★★★)
• Card and list views with expandable details
• Lifecycle filter tabs: All, Human, Learned, Released, Deprecated
• Health check button to run auto-maintenance
• Promote/deprecate per skill
• Bulk select/delete
• Inline editing and full skill designer

---

CLI

# Apply migrations (includes skills schema)
deno task migrate

# Run skills evaluation tests
deno test --allow-all tests/skills_eval_test.ts

# Start server to access Skills UI
cortex serve
# → http://127.0.0.1:3000 → Skills tab

---

Database

Table: procedural_memory in memory.db (17 columns, 8 indexes).

Migrations:

• 002_memory.sql — Initial table
• 014_skills_origin.sql — origin, content
• 017_skills_metadata.sql — metadata, indexes
• 023_skills_enhancements.sql — lifecycle, trust, health, deps, embedding

---

See Also

• Memory System — 5-tier memory architecture
• Agent Loop — How skills are injected into prompts
• REST API — Full API reference
• Contributing — How to add built-in skills