Manage Skills

Manage Skills

Meta-skill for managing, auditing, and maintaining all VRP Toolkit skills.

Core Functions

1. Audit Skills Directory

Compare actual skills in .claude/skills/ with SKILLS.md documentation.

Usage:

python .claude/skills/manage-skills/scripts/audit_skills.py

Reports:

• Skills in directory vs SKILLS.md
• Missing from documentation
• Missing from directory
• Sync status

2. Check Skill Compliance

Validate skills against VRP Toolkit standards.

Usage:

# Check specific skill
python .claude/skills/manage-skills/scripts/check_compliance.py skill-name

# Check all skills
python .claude/skills/manage-skills/scripts/check_compliance.py --all

Checks:

• Independence: Skill doesn't embed other skills' content
• Size: SKILL.md ≤ 500 lines (body, excluding frontmatter)
• Structure: Required files present, no prohibited files
• Frontmatter: Valid YAML with name and description
• References: All reference files mentioned in SKILL.md

See compliance_checklist.md for detailed standards.

3. Update SKILLS.md Index

Sync skills documentation in SKILLS.md with actual skills.

When:

• After adding new skill
• After removing skill
• After significantly modifying skill description

See: update_procedures.md → Section 1

4. Record Changes in SKILLS_LOG.md

Log all skill modifications for tracking and history.

When:

• After any skill change (add/update/remove/rename/split/merge)

Template:

## YYYY-MM-DD - [Action]: [skill-name]
**Action:** [Added/Updated/Removed/Renamed/Split/Merged]
**Reason:** [Why this change was made]
**Changes:**
- [Specific change 1]
- [Specific change 2]
**Compliance Notes:** [Any compliance issues addressed]
**Impact:** [How this affects other skills or workflows]

See: update_procedures.md → Section 2

Workflow Patterns

Pattern A: Add New Skill

1. Create skill using skill-creator
2. Run: audit_skills.py
   → Check if new skill appears in directory
3. Update SKILLS.md skills index (Section 1)
4. Record in SKILLS_LOG.md
5. Run: check_compliance.py skill-name
   → Verify new skill is compliant

Pattern B: Modify Existing Skill

1. Make changes to skill
2. Run: check_compliance.py skill-name
   → Check for violations (size, independence, etc.)
3. If issues found, fix them
4. Update SKILLS.md description if needed
5. Record changes in SKILLS_LOG.md

Pattern C: Periodic Audit

1. Run: audit_skills.py
   → Check directory vs SKILLS.md sync
2. Run: check_compliance.py --all
   → Check all skills for compliance
3. Review warnings and errors
4. Plan fixes or improvements
5. Update SKILLS_LOG.md with findings

Pattern D: Fix Compliance Issues

Size Violation (>500 lines):

1. Identify extractable sections
2. Move to references/ or create new skill
3. Update SKILL.md references
4. Re-run check_compliance.py
5. Record in SKILLS_LOG.md

Independence Violation:

1. Find embedded content from other skills
2. Replace with reference: "See [skill-name] for..."
3. Re-run check_compliance.py
4. Record in SKILLS_LOG.md

See update_procedures.md for detailed procedures on:

• Renaming skills
• Splitting large skills
• Merging similar skills
• Archiving deprecated skills

Integration with Other Skills

Works with:

• skill-creator - Use to create new skills before managing them
• update-migration-log - Similar logging pattern for migrations
• update-task-board - Similar documentation sync pattern

DO NOT embed workflows from these skills - Reference them instead.

Compliance Standards Quick Reference

Independence:
  ✓ Can reference other skills: "See [skill-name] for..."
  ✗ Cannot embed workflows from other skills

Size:
  ✓ SKILL.md ≤ 500 lines (excluding frontmatter)
  ⚠ Warning at 400 lines
  ✗ Error at 500 lines

Structure:
  ✓ Required: SKILL.md with valid frontmatter
  ✓ Optional: scripts/, references/, assets/
  ✗ Prohibited: README.md, CHANGELOG.md, etc.

Frontmatter:
  ✓ Required fields: name, description
  ✓ Description: 50-200 words with use cases
  ✗ Extra fields discouraged

References:
  ✓ All refs linked from SKILL.md
  ✓ Max 1 level deep (no nested dirs)
  ⚠ Warning if ref >500 lines

Full details: compliance_checklist.md

Files in This Skill

manage-skills/
├── SKILL.md                          # This file
├── scripts/
│   ├── audit_skills.py              # Directory vs CLAUDE.md audit
│   └── check_compliance.py          # Compliance validation
├── references/
│   ├── compliance_checklist.md      # Detailed compliance standards
│   └── update_procedures.md         # Step-by-step update procedures
└── assets/
    └── SKILLS_LOG_template.md       # Template for SKILLS_LOG.md

Tips

1. Run audit after adding skills - Catches missing documentation immediately
2. Check compliance before packaging - Prevents distribution of non-compliant skills
3. Keep SKILLS_LOG.md updated - Provides history for troubleshooting
4. Review warnings seriously - They often indicate real issues
5. Split before 500 lines - Easier to split at 400 than fix at 600

Limitations

• Does not automatically fix compliance issues (manual fixes required)
• Cannot detect semantic overlap between skills (manual review needed)
• Windows encoding issues with emoji in scripts (uses ASCII fallback)