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

• Run audit after adding skills - Catches missing documentation immediately

• Check compliance before packaging - Prevents distribution of non-compliant skills

• Keep SKILLS_LOG.md updated - Provides history for troubleshooting

• Review warnings seriously - They often indicate real issues

• 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)