Refactoring Skills

Refactoring Skills

Overview

Refactoring skills IS applying clean code principles to documentation.

Consolidate, simplify, extract shared conventions, remove redundancy.

Core principle: Fewer focused skills > many overlapping skills.

Routing

Pattern: Tree Handoff: mixed (auto-invoke per classification) Next: analyzing-agent-systems | writing-skills | writing-rules Chain: maintenance

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

1. Discover all skills
2. Analyze and classify
3. Execute refactoring plan
4. Extract shared conventions
5. Validate results
6. Generate report

Announce: "Created 6 tasks. Starting execution..."

Task 1: Discover All Skills

Goal: Find all skills in the project.

Search locations:

find . -name "SKILL.md" -type f 2>/dev/null
ls -la .claude/skills/ 2>/dev/null

Also check:

• Plugin directories
• User-level skills (~/.claude/skills/)

Document:

• Skill name
• Location
• Brief description

Verification: Complete list of all skills with locations.

Task 2: Analyze and Classify

Goal: Classify each skill for action, informed by systematic weakness analysis.

First: Invoke analyzing-agent-systems skill to get a comprehensive analysis report covering all 8 weakness categories. This replaces manual analysis.

Then classify each skill using both the analysis report and manual assessment:

Classification Matrix

Analysis-Informed Questions

For each skill, check against analysis report:

1. Did analysis flag routing/trigger weaknesses for this skill?
2. Did analysis find context management issues?
3. Did analysis detect overlap with other skills?
4. Is this skill referenced in any broken chain?
5. Does it follow current standards? (frontmatter, line count, sections)

Optional: External Search

If claude-skills-mcp is available:

mcp__claude-skills-mcp__search_skills query="[skill domain]"

Compare with community implementations. Better patterns exist?

Verification: Each skill has a classification and action, informed by analysis report.

Task 3: Execute Refactoring Plan

Goal: Apply the classified actions.

For Skills to Refactor

Invoke the writing-skills skill with the existing skill path.

For Skills to Merge

1. Identify the primary skill (keep this one)
2. Extract unique content from secondary skill
3. Integrate into primary skill
4. Delete secondary skill directory

For Skills to Delete

1. Confirm no dependencies (grep for skill name)
2. Remove entire skill directory
3. Remove from any manifest references

Important: One action at a time. Verify after each.

Verification: All classified actions executed.

Task 4: Extract Shared Conventions

Goal: Move duplicated conventions to rule files.

Signs of shared conventions:

• Same constraint appears in 2+ skills
• Convention is about "what" not "how"
• Convention is path-specific

Process:

1. Identify duplicated constraint
2. Invoke writing-rules skill to create rule
3. Remove constraint from all skills
4. Verify rule auto-injects correctly

Verification: No duplicated conventions across skills.

Task 5: Validate Results

Goal: Verify all remaining skills are valid.

For each skill:

python3 "${CLAUDE_SKILL_DIR}/../writing-skills/scripts/validate_skill.py" <skill-path>

Or manual checklist:

• Frontmatter has name and description
• Description states what the skill does, then "Use when..." triggers
• Body < 300 lines
• No duplicated conventions (now in rules)

Verification: All remaining skills pass validation.

Task 6: Generate Report

Goal: Document what was done.

Report Format

## Refactoring Summary

### Skills Analyzed: N

### Actions Taken:
| Skill | Action | Notes |
|-------|--------|-------|
| skill-name | kept/refactored/merged/deleted | details |

### Rules Extracted:
| Rule | Source Skills |
|------|--------------|
| rule-name | skill-a, skill-b |

### Recommendations:
- [Future improvements]

Verification: Report accurately reflects all changes.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "Keep all skills, they might be useful"
• "Too much overlap is fine"
• "Don't need to extract conventions"
• "Skip validation, I just fixed them"
• "Report is busywork"

All of these mean: You're about to leave mess behind. Follow the process.

Common Rationalizations

Skill Chain Reference (Maintenance)

References

• Use writing-skills skill for improving skills
• Use writing-rules skill for extracting conventions
• Use skill-reviewer subagent for quality checks