Improving Skills Skill | Agent Skills

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.

Violating the letter of the rules is violating the spirit of the rules.

Routing

Pattern: Node Handoff: none Next: none

Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

TaskCreate for EACH task below:
- Subject: "[improving-skills] Task N: <action>"
- ActiveForm: "<doing action>"

Tasks:

Analyze current skill
Gather project context
Research best practices
Identify improvements
Apply improvements
Validate and review

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

Execution rules:

TaskUpdate status="in_progress" BEFORE starting each task
TaskUpdate status="completed" ONLY after verification passes
If task fails → stay in_progress, diagnose, retry
NEVER skip to next task until current is completed
At end, TaskList to confirm all completed

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 2025
[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 starts with "Use when..."
[ ] Description doesn't summarize workflow
[ ] Has Task Initialization section
[ ] Has verification for each task
[ ] Has Red Flags section
[ ] Has Rationalizations table
[ ] Has flowchart
[ ] 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.

CRITICAL: Make focused edits, not full rewrites.

Order of changes:

Fix frontmatter (description)
Add Task Initialization if missing
Add verification criteria
Add Red Flags / Rationalizations
Extract verbose content to references
Add flowchart if missing

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 scripts/validate_skill.py <skill-path>

Or manual checklist:

[ ] Frontmatter valid
[ ] Description starts with "Use when..."
[ ] 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. |

Flowchart: Skill Improvement

digraph improve_skill {
    rankdir=TB;

    start [label="Improve skill", shape=doublecircle];
    analyze [label="Task 1: Analyze\ncurrent skill", shape=box];
    context [label="Task 2: Gather\nproject context", shape=box];
    research [label="Task 3: Research\nbest practices", shape=box];
    identify [label="Task 4: Identify\nimprovements", shape=box];
    apply [label="Task 5: Apply\nimprovements", shape=box];
    validate [label="Task 6: Validate\nand review", shape=box];
    pass [label="Review\npassed?", shape=diamond];
    done [label="Skill improved", shape=doublecircle];

    start -> analyze;
    analyze -> context;
    context -> research;
    research -> identify;
    identify -> apply;
    apply -> validate;
    validate -> pass;
    pass -> done [label="yes"];
    pass -> apply [label="no\nfix"];
}

References

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

Agent Skills: Improving Skills

Install this agent skill to your local

Skill Files