cortex-skills-loop

# Cortex Skills Loop

## Overview

The cortex CLI includes an AI-powered recommendation engine that learns from usage patterns. This
skill establishes the workflow for participating in that learning loop: get recommendations when
context shifts, provide feedback on recommendation quality, and rate skills after use. Each
interaction improves future recommendations.

## When to Engage

### Signals That Trigger Recommendations

Run `cortex skills recommend` when any of these mismatch signals appear:

- **File pattern shift** — `git diff` or the working set includes file types not covered by
  active skills (e.g., `.tf` Terraform files appear but no infrastructure skill is active,
  or `**/auth/**` paths get touched without security skills loaded)
- **Agent activation change** — a new agent gets activated that likely has complementary skills
  not yet loaded (the recommender maps agents to skill sets internally)
- **Explicit domain pivot** — the user switches focus to a different domain ("now let's handle
  the database migrations") and the current skill set is oriented elsewhere
- **Skill gap felt** — a task requires domain knowledge that no active skill covers, or an
  active skill is providing no value to the current work

### Signals That Trigger Rating/Feedback

- **Task completion** — a skill was active during work that just finished successfully
- **Recommendation acted on** — a recommendation was recently followed or dismissed
- **Negative experience** — a skill actively misled or produced unhelpful guidance

### When Not to Engage

Do **not** run recommendations on every session start or for routine tasks where the active
skill set is clearly appropriate. The loop adds value through selective, signal-driven use.

## Workflow

### 1. Recommend — Surface Relevant Skills

When a context change is detected, run:

```bash
cortex skills recommend
```

This analyzes the current git state, active agents, and historical patterns to suggest skills
grouped by confidence level:

- **High confidence (>=0.8):** Auto-activate candidates — consider activating immediately
- **Medium confidence (0.6-0.8):** Worth reviewing with the user
- **Low confidence (<0.6):** Informational only

To check what is currently active before acting on recommendations:

```bash
cortex status
```

For full option details: `cortex skills recommend --help`

### 2. Feedback — Improve Recommendation Quality

After a recommendation has been acted on (activated or dismissed), record whether it was useful:

```bash
cortex skills feedback <skill-name> helpful --comment "Caught auth vulnerability early"
cortex skills feedback <skill-name> not-helpful --comment "Not relevant to this API work"
```

Positive feedback with context available teaches the recommender to associate the current
project context with that skill for future sessions. Always provide a `--comment` when possible
to enrich the learning signal.

For full option details: `cortex skills feedback --help`

### 3. Rate — Record Skill Effectiveness

After a task completes and a skill was active during the work, rate its contribution:

```bash
cortex skills rate <skill-name> --stars <1-5> --review "Description of experience"
```

Additional flags to enrich the signal:

- `--helpful` / `--not-helpful` — binary usefulness indicator
- `--succeeded` / `--failed` — whether the task the skill supported succeeded

Ratings feed back into the recommendation engine. Highly rated skills get prioritized in
future suggestions; low-rated skills get demoted.

To view existing ratings before adding one: `cortex skills ratings <skill-name>`

To discover top-performing skills: `cortex skills top-rated`

For full option details: `cortex skills rate --help`

## Closing the Loop

The recommend-feedback-rate cycle is cumulative. Each interaction updates the SQLite-backed
learning database, improving four recommendation strategies:

1. **Semantic similarity** — embeds successful session contexts for future matching
2. **Rule-based** — matches file patterns to skill suggestions
3. **Agent-based** — maps active agents to complementary skills
4. **Pattern-based** — promotes skills with high historical success rates

When multiple strategies converge on the same skill, confidence gets boosted. Consistent
feedback and ratings are what make this convergence happen over time.

## Quick Reference

| Action | Command |
|--------|---------|
| Get recommendations | `cortex skills recommend` |
| Check current status | `cortex status` |
| Give positive feedback | `cortex skills feedback <skill> helpful --comment "..."` |
| Give negative feedback | `cortex skills feedback <skill> not-helpful --comment "..."` |
| Rate a skill (1-5 stars) | `cortex skills rate <skill> --stars N --review "..."` |
| View skill ratings | `cortex skills ratings <skill>` |
| See top-rated skills | `cortex skills top-rated` |
| View usage analytics | `cortex skills analytics` |