---
title: "Skill Candidates"
description: "List and promote session-learned skill candidates to org-private tier"
canonical: "https://docs.ainative.studio/docs/zeromemory/skill-candidates"
last-updated: "2026-10-13T21:42:35.442Z"
---

# Skill Candidates

Source: https://docs.ainative.studio/docs/zeromemory/skill-candidates

> List and promote session-learned skill candidates to org-private tier

## Skill Candidates

ZeroMemory automatically extracts skill candidates from agent session activity. When an agent repeatedly applies a behavior pattern with high confidence, it surfaces as a skill candidate that can be promoted to an org-private reusable skill.

## List Skill Candidates

```bash
curl "https://api.ainative.studio/api/v1/public/memory/v2/skill-candidates?min_confidence=0.6" \
  -H "x-api-key: $API_KEY"
```

Response:

```json
{
  "candidates": [
    {
      "name": "sql-query-optimizer",
      "description": "Rewrites N+1 queries using JOIN and prefetch patterns",
      "confidence": 0.91,
      "reinforcement_count": 5,
      "extracted_at": "2026-05-18T14:30:00Z",
      "ready_for_promotion": true
    },
    {
      "name": "pytest-fixture-builder",
      "description": "Generates reusable pytest fixtures from test setup code",
      "confidence": 0.74,
      "reinforcement_count": 2,
      "extracted_at": "2026-05-17T09:10:00Z",
      "ready_for_promotion": false
    }
  ],
  "total": 2
}
```

**`ready_for_promotion`** is `true` when `confidence >= 0.8` AND `reinforcement_count >= 3`.

## Promote a Skill Candidate

```bash
curl -X POST "https://api.ainative.studio/api/v1/public/memory/v2/skill-candidates/sql-query-optimizer/promote" \
  -H "x-api-key: $API_KEY"
```

Response:

```json
{
  "status": "promoted",
  "name": "sql-query-optimizer",
  "origin": "org:my-org-id"
}
```

Returns `422` if the candidate has not met the promotion threshold:

```json
{
  "detail": "Skill not ready for promotion: confidence=0.74 (need 0.8), reinforcement=2 (need 3)"
}
```

## Python SDK

```python
import requests

API_KEY = "your-api-key"
BASE = "https://api.ainative.studio/api/v1/public/memory/v2"
headers = {"x-api-key": API_KEY}

## List candidates ready for promotion
r = requests.get(f"{BASE}/skill-candidates", headers=headers, params={"min_confidence": 0.8})
candidates = r.json()["candidates"]

for c in candidates:
    if c["ready_for_promotion"]:
        result = requests.post(
            f"{BASE}/skill-candidates/{c['name']}/promote",
            headers=headers,
        ).json()
        print(f"Promoted: {result['name']} → {result['origin']}")
```

## Promotion Requirements

| Condition | Threshold | Description |
|-----------|-----------|-------------|
| `confidence` | >= 0.8 | Model's certainty that the pattern is a generalizable skill |
| `reinforcement_count` | >= 3 | Number of sessions where the skill was independently applied |

Both conditions must be met. Promoted skills are stored as `semantic` memory at `org-private` tier and are available to all agents in the organization.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/memory/v2/skill-candidates` | List session-learned skill candidates (filterable by `min_confidence`) |
| POST | `/memory/v2/skill-candidates/{name}/promote` | Promote candidate to org-private skill tier |