Skip to main content

​
Graduation Manager

The Graduation Manager automatically promotes external skills to local trusted skills based on proven adoption metrics. When an external skill demonstrates consistent success (85%+ confidence, 5+ uses, 80%+ success rate), it becomes eligible for graduation.

​
createGraduationManager

Creates a graduation manager instance that handles skill lifecycle management. 
import { createGraduationManager } from 'auto-skill/core/graduation-manager';

const manager = createGraduationManager(
  '/path/to/skills_tracking.db',
  '/path/to/graduated-skills'
);
​
trackerDbPath
string
required
Path to the skill tracker SQLite database (reserved for future use)
​
skillsOutputDir
string
required
Directory to save graduated skill files
​
manager
object
Returns an object with graduation detection, execution, history, and statistics methods.

​
GraduationCandidate Type

Represents a skill eligible for graduation from external to local. 
interface GraduationCandidate {
  skillName: string;
  currentConfidence: number;
  usageCount: number;
  successCount: number;
  successRate: number;
  firstUsed: string;        // ISO-8601 timestamp
  lastUsed: string;         // ISO-8601 timestamp
  source: string;           // "external" | "mental-hint"
  metadata?: Record<string, unknown> | null;
}

​
Graduation Criteria

Skills must meet all three thresholds to graduate:
  • Minimum Confidence: 0.85 (85%)
  • Minimum Usage Count: 5 uses
  • Minimum Success Rate: 0.80 (80%)

​
Methods

​
detectCandidates

Detect skills eligible for graduation from aggregated statistics. 
const candidates = manager.detectCandidates(stats);
​
stats
Record<string, Record<string, unknown>>
required
Aggregated per-skill statistics keyed by skill name. Each skill entry should include:
  • source: “external” | “mental-hint” | “local”
  • confidence: number (0-1)
  • usage_count: number
  • success_count: number
  • first_used: ISO-8601 timestamp
  • last_used: ISO-8601 timestamp
  • metadata: optional metadata object
​
candidates
GraduationCandidate[]
Array of graduation candidates sorted by confidence (highest first). Excludes:
  • Already graduated skills
  • Local skills
  • Skills not meeting criteria thresholds

​
graduateSkill

Graduate a single skill candidate to a local SKILL.md file. 
const skillPath = manager.graduateSkill(candidate);
​
candidate
GraduationCandidate
required
The graduation candidate to promote
​
skillPath
string | null
Absolute path to the generated skill file, or null on failure.
Side effects:
  • Writes a SKILL.md file with YAML frontmatter and graduation metadata
  • Appends entry to graduation_log.json
  • Sets graduated skill confidence to 0.80 (local)

​
autoGraduateAll

Automatically graduate the top candidates without user prompting. 
const graduated = manager.autoGraduateAll(stats, 5);
​
stats
Record<string, Record<string, unknown>>
required
Aggregated per-skill statistics
​
maxCount
number
default:"5"
Maximum number of skills to graduate
​
graduated
string[]
Array of paths to graduated skill files

​
getGraduationHistory

Retrieve the full graduation history. 
const history = manager.getGraduationHistory();
​
history
Array<Record<string, unknown>>
Array of graduation log entries. Each entry contains:
  • skill_name: string
  • graduated_at: ISO-8601 timestamp
  • graduated_from: “external” | “mental-hint”
  • usage_count: number
  • success_rate: number
  • final_confidence: 0.80
  • skill_path: absolute path to skill file

​
statsSummary

Get a summary of graduation statistics. 
const summary = manager.statsSummary(stats);
​
stats
Record<string, Record<string, unknown>>
required
Aggregated per-skill statistics (used to count pending candidates)
​
summary
Record<string, unknown>
Object with graduation statistics:
  • total_graduated: number
  • pending_candidates: number
  • graduation_rate: string (percentage)
  • recent_graduations: array of last 5 graduation entries

​
Graduation Workflow

import { createGraduationManager } from 'auto-skill/core/graduation-manager';
import { createSkillTracker } from 'auto-skill/core/skill-tracker';

// 1. Create manager and tracker
const manager = createGraduationManager(
  '~/.claude/auto-skill/skills_tracking.db',
  '~/.claude/skills/graduated'
);

const tracker = createSkillTracker();

// 2. Build stats from tracker
const adoptions = tracker.listAdoptions(0.5);
const stats: Record<string, Record<string, unknown>> = {};

for (const adoption of adoptions) {
  stats[adoption.skillName] = {
    source: adoption.source,
    confidence: adoption.currentConfidence,
    usage_count: adoption.usageCount,
    success_count: adoption.successCount,
    first_used: adoption.firstUsed,
    last_used: adoption.lastUsed,
    metadata: {}
  };
}

// 3. Detect candidates
const candidates = manager.detectCandidates(stats);
console.log(`Found ${candidates.length} graduation candidates`);

// 4. Graduate top 3 candidates
const graduated = manager.autoGraduateAll(stats, 3);
console.log(`Graduated ${graduated.length} skills:`);
graduated.forEach(path => console.log(`  - ${path}`));

// 5. View history
const history = manager.getGraduationHistory();
console.log(`\nTotal graduated: ${history.length}`);

// 6. Get summary
const summary = manager.statsSummary(stats);
console.log(`Graduation rate: ${summary.graduation_rate}`);

​
Generated Skill Format

Graduated skills are saved as SKILL.md files with YAML frontmatter: 
---
name: fix-type-errors
confidence: 0.80

# Source
source: local
derived-from: external
graduated-at: 2026-03-03T10:30:00.000Z

# Adoption stats
usage-count: 12
success-rate: 0.92
first-used: 2026-02-15T08:00:00.000Z
last-used: 2026-03-02T16:45:00.000Z

# Vercel compatibility
compatible-agents: [claude-code, opencode, codex]
tags: ["typescript", "debugging"]
---

# fix-type-errors

**Graduated from**: external
**Status**: Local (promoted from external)

## Description

Fixes TypeScript type errors by analyzing error messages and applying appropriate type annotations.

## Why This Skill Was Graduated

This skill was automatically graduated from external to local based on proven adoption:

- **Usage**: 12 times
- **Success Rate**: 92%
- **Final Confidence**: 80% (local)

The skill has been validated through real-world usage and promoted to a trusted local skill.

​
Source Reference

src/core/graduation-manager.ts:163-402

Build docs developers (and LLMs) love

Get started for freeTalk to us