Overview Skill Graduation is Auto-Skill’s mechanism for promoting battle-tested external skills to trusted local skills. As you use external skills and they prove reliable, Auto-Skill automatically tracks their confidence and usage, eventually “graduating” them to local status.
Confidence Evolution : External skills start at 50%, increase to 75% with usage, and graduate to 80% as local skills.
How It Works Graduation Criteria A skill becomes eligible for graduation when it meets all three thresholds:
Confidence ≥ 85% High confidence score from successful uses
Usage Count ≥ 5 uses Proven through repeated usage
Success Rate ≥ 80% High success rate in real workflows
src/core/graduation-manager.ts
/** Minimum confidence score required for graduation. */ const MIN_CONFIDENCE = 0.85 ; /** Minimum number of uses required for graduation. */ const MIN_USAGE_COUNT = 5 ; /** Minimum success rate required for graduation. */ const MIN_SUCCESS_RATE = 0.80 ; function meetsCriteria ( candidate : GraduationCandidate ) : boolean { return ( candidate . currentConfidence >= MIN_CONFIDENCE && candidate . usageCount >= MIN_USAGE_COUNT && candidate . successRate >= MIN_SUCCESS_RATE ); }
Graduation Process
Detection
Auto-Skill analyzes aggregated usage statistics to detect graduation candidates.
Candidate Ranking
Eligible skills are ranked by confidence (highest first).
Skill Generation
A new local SKILL.md file is generated with graduation metadata.
Logging
The graduation is recorded in graduation_log.json for tracking.
Graduation Candidate The system tracks candidates with detailed metrics:
export interface GraduationCandidate { skillName : string ; currentConfidence : number ; usageCount : number ; successCount : number ; successRate : number ; firstUsed : string ; lastUsed : string ; source : string ; // "external" | "mental-hint" metadata : Record < string , unknown > | null ; }
Generated Skill Structure When a skill graduates, Auto-Skill generates a comprehensive SKILL.md file:
--- name : react-testing-patterns confidence : 0.80 # Source source : local derived-from : vercel/react-skills graduated-at : 2024-03-15T10:30:00Z # Adoption stats usage-count : 12 success-rate : 0.92 first-used : 2024-03-01T08:00:00Z last-used : 2024-03-15T09:45:00Z # Vercel compatibility compatible-agents : [ claude-code , opencode , codex ] tags : [ "react" , "testing" , "jest" ] --- # react-testing-patterns **Graduated from** : vercel/react-skills **Status** : Local (promoted from external) ## Description Best practices for testing React components with Jest and React Testing Library. ## Why This Skill Was Graduated This skill was automatically graduated from external (vercel/react-skills) 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. ## Original Metadata - **Original Author** : Vercel - **Community Installs** : 1,234 - **Original Source** : https://skills.sh/vercel/react-skills ## Usage Use this skill by referencing it in your workflow...
Frontmatter Generation
buildGraduatedSkillContent()
function buildGraduatedSkillContent ( candidate : GraduationCandidate ) : string { const metadata = ( candidate . metadata ?? {}) as Record < string , unknown >; const now = new Date (). toISOString (); let frontmatter = `--- name: ${ candidate . skillName } confidence: 0.80 # Source source: local derived-from: ${ candidate . source } graduated-at: ${ now } # Adoption stats usage-count: ${ candidate . usageCount } success-rate: ${ candidate . successRate . toFixed ( 2 ) } first-used: ${ candidate . firstUsed || "unknown" } last-used: ${ candidate . lastUsed || "unknown" } # Vercel compatibility compatible-agents: [claude-code, opencode, codex] tags: ${ JSON . stringify (( metadata . tags as string []) ?? []) } --- \n\n ` ; // ... build body with description, graduation reason, metadata return frontmatter + body ; }
Usage Detect Candidates Find skills eligible for graduation:
import { createGraduationManager } from "auto-skill" ; const manager = createGraduationManager ( "~/.claude/auto-skill/tracker.db" , "~/.claude/skills/auto" ); const stats = { "react-testing" : { source: "external" , confidence: 0.87 , usage_count: 12 , success_count: 11 , }, // ... more skill stats }; const candidates = manager . detectCandidates ( stats ); console . log ( `Found ${ candidates . length } graduation candidates:` ); for ( const candidate of candidates ) { console . log ( `- ${ candidate . skillName } ` ); console . log ( ` Confidence: ${ Math . round ( candidate . currentConfidence * 100 ) } %` ); console . log ( ` Usage: ${ candidate . usageCount } ( ${ Math . round ( candidate . successRate * 100 ) } % success)` ); }
Found 3 graduation candidates: - react-testing-patterns Confidence: 87% Usage: 12 (92% success) - nextjs-deployment Confidence: 85% Usage: 8 (88% success) - typescript-strict-mode Confidence: 86% Usage: 6 (83% success)
Graduate a Single Skill const candidate = candidates [ 0 ]; const skillPath = manager . graduateSkill ( candidate ); if ( skillPath ) { console . log ( `✅ Graduated to: ${ skillPath } ` ); } else { console . log ( `❌ Graduation failed` ); }
Auto-Graduate All Eligible // Automatically graduate top 5 candidates const graduated = manager . autoGraduateAll ( stats , 5 ); console . log ( `✅ Graduated ${ graduated . length } skills:` ); for ( const path of graduated ) { console . log ( ` - ${ path } ` ); }
Graduation History Auto-Skill maintains a graduation log at ~/.claude/skills/auto/graduation_log.json:
[ { "skill_name" : "react-testing-patterns" , "graduated_at" : "2024-03-15T10:30:00Z" , "graduated_from" : "external" , "usage_count" : 12 , "success_rate" : 0.92 , "final_confidence" : 0.80 , "skill_path" : "/home/user/.claude/skills/auto/react-testing-patterns.md" } ]
View History const history = manager . getGraduationHistory (); console . log ( `Total graduated: ${ history . length } ` ); for ( const entry of history . slice ( - 5 )) { console . log ( `- ${ entry . skill_name } ` ); console . log ( ` From: ${ entry . graduated_from } ` ); console . log ( ` Date: ${ entry . graduated_at } ` ); }
Graduation Statistics const summary = manager . statsSummary ( stats ); console . log ( `Graduation Rate: ${ summary . graduation_rate } ` ); console . log ( `Total Graduated: ${ summary . total_graduated } ` ); console . log ( `Pending Candidates: ${ summary . pending_candidates } ` );
API Reference createGraduationManager(trackerDbPath, skillsOutputDir) Path to the skill tracker SQLite database (reserved for future use)
Directory to save graduated skill files (e.g., ~/.claude/skills/auto)
Methods detectCandidates
(stats: Record<string, Record<string, unknown>>) => GraduationCandidate[]
Detect skills eligible for graduation from aggregated stats. Filters for external or mental-hint skills that meet confidence, usage, and success-rate thresholds. Returns: Candidates sorted by confidence (highest first)
graduateSkill
(candidate: GraduationCandidate) => string | null
Graduate a single skill candidate to a local SKILL.md file. Returns: Path to the generated skill file, or null on failure
autoGraduateAll
(stats: Record<string, Record<string, unknown>>, maxCount?: number) => string[]
Automatically graduate the top candidates without user prompting. Parameters:
stats - Aggregated per-skill statisticsmaxCount - Maximum number to graduate (default: 5) Returns: Array of paths to graduated skill filesgetGraduationHistory
() => Array<Record<string, unknown>>
Retrieve the full graduation history. Returns: Array of graduation log entries
statsSummary
(stats) => Record<string, unknown>
Get a summary of graduation statistics. Returns: { total_graduated : number ; pending_candidates : number ; graduation_rate : string ; // e.g., "65.5%" recent_graduations : Array < Record < string , unknown >> ; }
CLI Commands List Candidates npx auto-skill graduate --list
Graduate Interactively Prompts you to select skills to graduate.
Auto-Graduate npx auto-skill graduate --auto --max 5
Automatically graduates up to 5 eligible skills.
View History npx auto-skill graduate --history
Best Practices
Let skills prove themselves
Don’t manually force graduation. Let external skills accumulate usage and demonstrate reliability before promoting them.
After graduation, review the generated SKILL.md file and customize it if needed. The auto-generated content is a starting point.
Monitor skill telemetry to ensure graduated skills maintain their success rates. Low-performing graduated skills can be demoted or improved.
See Also
External Skills Load skills from Skills.sh
Telemetry Track skill usage and effectiveness