Skills System

Skills System

Skills are codified expertise — reusable procedural patterns that bridge reasoning and action. They represent the procedural memory tier in CortexPrism's 5-tier memory architecture.

Skill Sources

Skills can originate from three sources:

Source	Origin	Trust	Description
Built-in	builtin	Tier 4 (vetted)	TypeScript modules in packages/ai/src/skills/builtin/ — ship with CortexPrism
Filesystem	human	Tier 3 (trusted)	Markdown files in .cortex/skills/<name>/SKILL.md with YAML frontmatter
LLM-learned	llm	Tier 1 (untrusted)	Automatically extracted from successful agent tool-call sequences

Data Model

Skills are stored in the procedural_memory table in memory.db with 17 columns:

Column	Type	Description
name	TEXT PK	Unique skill identifier
description	TEXT	What the skill does
content	TEXT	Full Markdown instructions
steps	JSON	Ordered procedure steps
trigger_pattern	TEXT	When to suggest this skill
origin	TEXT	human, llm, or builtin
lifecycle	TEXT	Current lifecycle state
trust_tier	INTEGER	1-4 trust ranking
version	INTEGER	Monotonic version counter
success_rate	REAL	Rolling Bayesian average
utility_score	REAL	Composite quality from usage + success
freshness	REAL	30-day half-life decay score
last_used_at	TEXT	ISO timestamp of last use
depends_on	JSON	Array of prerequisite skill names
conflicts_with	JSON	Array of conflicting skill names
parent_skill_id	TEXT	For hierarchical skill trees
tags	JSON	Searchable tag array

Lifecycle (6 States)

candidate → verified → released → degraded → deprecated → archived
   ↑                      ↓           ↓           ↓
   └── LLM extraction      └── human   └── health  └── manual
                            promotion   degradation  deprecation

State	Description	Agent Exposure
candidate	Newly extracted by LLM, not reviewed	No (needs promotion)
verified	Reviewed and confirmed useful	Yes (if trust tier allows)
released	Production-ready, actively maintained	Yes
degraded	Quality dropped below threshold	Limited (warning in prompt)
deprecated	Scheduled for removal	No
archived	Removed from active use, retained for history	No

Retrieval & Matching

Skills are matched to user queries using a two-tier strategy:

Primary: Embedding-Based (Cosine Similarity)

When an embedding provider is available:

1. Pre-computed embeddings from skill name + description + content
2. Query embedding computed at match time
3. Skills ranked by cosine similarity
4. Quality-weighted re-ranking (utility_score × freshness × similarity)

Fallback: Lexical Matching

When no embedder is available:

1. Keyword extraction from user query
2. Trigger pattern matching (LIKE %pattern%)
3. Description text search (FTS5 or LIKE)

Reliability Filtering

Before skills are exposed to agents, filterReliableSkills() gates based on:

• Trust tier ≥ 2 for general use (untrusted LLM skills excluded)
• Success rate ≥ 0.3 for learned skills
• Lifecycle not deprecated or archived
• Health score above degradation threshold

Quality & Health

Composite Health Score

health_score = utility × 0.4 + (1 - redundancy) × 0.2 + freshness × 0.2 + (1 - failure_risk) × 0.2

Where:

• utility_score = Bayesian rolling average of success × success bonus
• redundancy = penalty from near-duplicate skills
• freshness = 2^(-days_since_last_use / 30) — 30-day half-life
• failure_risk = 1 - success_rate

Automatic Maintenance

runSkillHealthMaintenance() runs periodically:

• Deprecates skills below minimum health score
• Degrades skills with sustained quality drops
• Flags near-duplicate skills for review

Deduplication & Merging

Detection

findSimilarSkills() uses embedding similarity to detect near-duplicates.

Merging

mergeSkill() combines two skills:

• Steps from both skills merged and deduplicated
• Descriptions combined
• Source skill archived
• Target skill version bumped
• Dependents updated

Auto-Deduplication

After each LLM extraction session, deduplicateExtractedSkill() checks if the newly extracted skill is too similar to an existing one and auto-merges if so.

Dependency Tracking

Skills can declare relationships via depends_on and conflicts_with:

{
  "depends_on": ["cortex-dev", "frontend-design"],
  "conflicts_with": ["legacy-pattern"]
}

• getSkillDependencies() — traverse prerequisite chain
• getSkillDependents() — find all skills that depend on this one
• deleteSkill() blocks deletion if other skills depend on the target

Trust Tiering (4 Levels)

Tier	Label	Icon	Description
1	Untrusted	★☆☆☆	LLM-extracted, not reviewed
2	Provisional	★★☆☆	Reviewed once, needs more validation
3	Trusted	★★★☆	Human-authored, vetted
4	Vetted	★★★★	Built-in, ships with CortexPrism

Agent Tools

load_skill

Loads a skill's full instructions into the agent context. Auto-records last_used_at for freshness tracking.

skill_read

Read or list skills with optional origin/lifecycle filtering. Display includes trust stars and lifecycle badges.

skill_write

8 operations: create, update, delete, merge, promote, deprecate, dependents, dependencies.

Web UI

• Card/List views — toggle between visual cards and compact list
• Lifecycle badges — color-coded by state (green=released, yellow=candidate, red=deprecated)
• Trust stars — ★☆☆☆ to ★★★★ visual indicators
• Stats bar — total, utility, freshness scores
• Skill designer — full-screen split-pane editor with live preview
• Lifecycle filter tabs — Released, Deprecated, Candidate
• Health check — run maintenance cycle on demand
• Dependency viewer — visualize skill relationship graph

API Endpoints

Method	Path	Description
GET	/api/skills	List skills (optional ?origin= and ?lifecycle=)
GET	/api/skills/stats	Skill statistics
GET	/api/skills/detail?name=	Full skill details
POST	/api/skills	Create a new skill
POST	/api/skills/merge	Merge two skills
POST	/api/skills/deprecate	Deprecate a skill
POST	/api/skills/promote	Promote lifecycle state
POST	/api/skills/load-human	Load from .cortex/skills/
POST	/api/skills/export	Export to SKILL.md
GET	/api/skills/dependencies?name=	Dependency tree
GET	/api/skills/health?name=	Health scores
DELETE	/api/skills?name=	Delete a skill

See Also

• Memory System — 5-tier memory architecture
• Built-in Tools — Skill-related agent tools
• Developing Plugins — Extending with custom skills

Skill Bus Bindings (#54)

The skill bus orchestrates event-driven skill execution. Each binding connects a skill to a system event with conditions and actions.

Binding Structure

Field	Description
skillId	Target skill
eventType	Trigger event (e.g., tool_call, agent_turn_end)
conditions	Match filters (type, match patterns)
action	Response action (invoke_skill, inject_context, emit_event, call_tool, notify)
priority	Execution order
cooldown	Minimum interval between triggers
enabled	Active/inactive toggle

API Endpoint

GET /api/skills/bindings returns:

• All configured bindings enriched with skill name/description
• Bus status (total, enabled, cooldowns, recent events)
• Recent event log with triggered bindings and per-binding results

Web UI

Skills page has a 🔗 Bindings toggle:

• Binding cards showing skill name, event type, action, priority, conditions
• Recent event log with type, fired count, pass/fail, timestamp