Skip to main content

​
auto-skill graduate

Manage skill graduation from auto-generated to permanent status. Skills that meet graduation criteria (high confidence, sufficient usage, good success rate) can be promoted to permanent skills.

​
Usage

auto-skill graduate [action] [options]

​
Actions

​
detect
action
default:"true"
Detect skills that are ready for graduation based on usage metrics
​
promote
action
Promote a specific skill to permanent status

​
Options

​
--max
string
default:"5"
Maximum number of skills to graduate at once
​
--json
boolean
default:"false"
Output results in JSON format

​
Graduation Criteria

Skills are eligible for graduation when they meet ALL of these criteria:
1

High Confidence

Confidence score ≥ 85%
2

Sufficient Usage

Used successfully at least 5 times
3

High Success Rate

Success rate ≥ 80%

​
Confidence Evolution

Skills progress through confidence levels as they’re used:
StageConfidenceSourceStatus
External50%Skills.shSuggested but unproven
Local75%Auto-generatedProven in your workflow
Graduated85%+PromotedBattle-tested and reliable

​
What Happens During Graduation

1

Validation

Verify the skill meets graduation criteria
2

Metadata Update

Update skill frontmatter to mark as graduated
3

Move to Permanent

Move from ~/.claude/skills/auto/ to ~/.claude/skills/
4

Update Symlinks

Update cross-agent symlinks to new location
5

Lock File Update

Re-lock skill with new content hash

​
Examples

​
Detect Graduation Candidates

auto-skill graduate detect

Graduation: detect

No graduation candidates yet.
Criteria: confidence >= 85%, usage >= 5, success rate >= 80%
Skills need to be used multiple times before they’re eligible for graduation. Keep using Auto-Skill, and candidates will appear automatically.

​
Detect with Results

Graduation Candidates (3)

  debug-api-errors
     Confidence: 88% | Uses: 12 | Success: 92%
     Ready for promotion

  tdd-workflow
     Confidence: 85% | Uses: 8 | Success: 87%
     Ready for promotion

  react-testing-utils
     Confidence: 86% | Uses: 6 | Success: 83%
     Ready for promotion

​
Promote Skills

auto-skill graduate promote
Promotes all eligible skills (up to --max limit) to permanent status.

​
Limit Promotions

auto-skill graduate promote --max 2
Promote at most 2 skills per run.

​
JSON Output

auto-skill graduate detect --json

{
  "action": "detect",
  "candidates": []
}

​
Skill Lifecycle

​
Benefits of Graduation

Higher Trust

Graduated skills have proven reliability in your workflow

Better Recommendations

Higher confidence leads to more prominent suggestions

Permanent Status

Won’t be auto-deleted during cleanup operations

Share with Team

Graduated skills are good candidates for team sharing

​
Hybrid Graduation

When a local pattern matches a community skill from Skills.sh, Auto-Skill suggests hybrid graduation: 
auto-skill graduate detect

Graduation Candidates (1)

  your-local-pattern
     Type: hybrid
     Confidence: 92%
     Matches: "React Test Patterns" (skills.sh)
     Recommendation: Replace local pattern with community skill
     Reason: Community skill is more comprehensive and maintained
Hybrid graduation means:
  1. Your local pattern is working well (75%+ confidence)
  2. A similar, better-maintained community skill exists
  3. Auto-Skill recommends adopting the community skill instead

​
Auto-Graduation

If enabled in config, Auto-Skill will automatically graduate eligible skills:
~/.claude/auto-skill.local.md
---
hybrid:
  auto_graduate: true  # Enable auto-graduation
---
With auto-graduation:
  • Skills meeting criteria are promoted automatically
  • No manual graduate promote needed
  • User confirmation still required for hybrid graduation
Auto-graduation is convenient but reduces control. Disable if you want to manually review all promotions.

​
Check Graduation Status

To see which skills are graduated: 
# View telemetry to see confidence scores
auto-skill telemetry report

# Check skill metadata
cat ~/.claude/skills/your-skill/SKILL.md
Graduated skills have graduated: true in their frontmatter.

​
Troubleshooting

Skills need more usage before graduation. Criteria:
  • At least 5 successful uses
  • At least 80% success rate
  • At least 85% confidence
Keep using the skills, and they’ll eventually qualify.
Low confidence despite high usage could mean:
  • Low success rate (below 80%)
  • The skill is too generic or broad
  • Recent failures lowered the score
Check telemetry:
auto-skill telemetry report --skill your-skill
You can manually edit the skill’s frontmatter:
---
name: your-skill
graduated: true
confidence: 0.85
---
Then move it to ~/.claude/skills/ and update symlinks.

View Telemetry

Check skill usage and success rates

Discover Patterns

Find new patterns to eventually graduate

Build docs developers (and LLMs) love

Get started for freeTalk to us