improving-skills

name	improving-skills
description	Optimizes a single existing skill through analysis, best-practice research, and targeted edits. Use when user says "improve skill", "optimize skill", "update skill", "skill needs work". Use when one specific skill is outdated or underperforming. NOT for multi-skill consolidation (use refactoring-skills instead).

Improving Skills

Overview

Improving skills IS refactoring documentation for clarity and effectiveness.

Analyze current state, research best practices, apply targeted improvements.

Core principle: Improve what exists—don't rewrite from scratch unless necessary.

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

1. Analyze current skill
2. Gather project context
3. Research best practices
4. Identify improvements
5. Apply improvements
6. Validate and review

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

Task 1: Analyze Current Skill

Goal: Understand the skill's current state.

Read the skill:

cat <skill-path>/SKILL.md
ls -la <skill-path>/

Document:

• Purpose: What does it do?
• Triggers: What activates it?
• Structure: How is it organized?
• References: What supporting files exist?
• Issues: What problems are apparent?

Common issues:

• Vague triggers in description
• Missing verification criteria
• No task list enforcement
• Missing Red Flags/Rationalizations
• Content that should be in references

Verification: Have documented purpose, triggers, and issues.

Task 2: Gather Project Context

Goal: Understand how the skill fits the project.

Search for usage:

grep -r "[skill-name]" . --include="*.md"

Questions:

• How often is this skill used?
• What files does it typically work on?
• Are there project-specific conventions it should follow?
• Does it overlap with other skills?

Verification: Understand skill's role in project context.

Task 3: Research Best Practices

Goal: Find current best practices for the skill's domain.

WebSearch:

[skill domain] best practices [current year]
[skill domain] patterns

Optional: External skills search

If claude-skills-mcp is available:

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

Compare with community implementations.

Verification: Have list of best practices to consider.

Task 4: Identify Improvements

Goal: Create specific improvement plan.

Check against standards:

• Description states what the skill does, then "Use when..." triggers
• Description doesn't enumerate workflow steps
• Task Initialization present if multi-step
• Has verification for each task
• Red Flags / Rationalizations present if there's real risk
• Body < 300 lines
• Details in references

Improvement types:

Issue	Improvement
Vague triggers	Add specific "Use when..." phrases
No task list	Add Task Initialization section
No verification	Add verification criteria per task
No Red Flags	Add anti-rationalization section
Too long	Extract to references
Outdated	Update to current best practices

Verification: Have specific list of improvements to make.

Task 5: Apply Improvements

Goal: Make targeted edits to the skill.

Important: Make focused edits, not full rewrites.

Order of changes:

1. Fix frontmatter (description)
2. Add Task Initialization if the flow is multi-step
3. Add verification criteria
4. Add Red Flags / Rationalizations if there's real risk
5. Extract verbose content to references

For each change:

• Make the edit
• Verify it's correct
• Move to next change

Verification: All identified improvements applied.

Task 6: Validate and Review

Goal: Verify skill meets quality standards.

Validation:

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

Or manual checklist:

• Frontmatter valid
• Description states what the skill does, then "Use when..." triggers
• Has Task Initialization
• All tasks have verification
• Has Red Flags
• Has Rationalizations
• Body < 300 lines

Quality review:

Invoke skill-reviewer subagent:

Task tool:
- subagent_type: "rcc:skill-reviewer"
- prompt: "Review skill at [path]"

Outcomes:

• Pass → Done
• Needs Fix → Fix and re-run
• Fail → Consider full rewrite with writing-skills

Verification: skill-reviewer returns "Pass".

Red Flags - STOP

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

• "Just rewrite the whole thing"
• "Skip research, I know best practices"
• "This skill is fine as-is"
• "Skip validation, changes are small"
• "Red Flags aren't needed for this skill"

All of these mean: You're about to make things worse. Follow the process.

Common Rationalizations

Excuse	Reality
"Full rewrite"	Targeted fixes preserve what works. Edit, don't rewrite.
"Skip research"	Best practices evolve. Check current standards.
"Fine as-is"	If you're here, something needs improvement. Find it.
"Skip validation"	Small changes can break things. Validate.
"No Red Flags"	Every discipline skill needs anti-rationalization.

References

• Use writing-skills skill for full rewrites
• Use skill-reviewer subagent for quality review
• See writing-skills/references/ for standards