Produces a maintained skills directory with updated names, unified terminology, repaired cross-references, and a git commit documenting every change and what was preserved. Use when: 'update these skill names', 'refactor the skills directory', 'clean up skill references', 'rename this skill', 'audit the skills ecosystem', 'deprecate this skill', 'add version history to a skill'.
Produces a maintained skills directory with updated names, unified terminology, repaired cross-references, and a git commit documenting every change and what was preserved. Use when: 'update these skill names', 'refactor the skills directory', 'clean up skill references', 'rename this skill', 'audit the skills ecosystem', 'deprecate this skill', 'add version history to a skill'.
category
skill-forge
triggers
["update these skill names","refactor the skills directory","clean up skill references","rename this skill","audit the skills ecosystem","deprecate this skill"]
tier
1
agents
["primary"]
tool_dependencies
["file_system","bash"]
inputs
[{"name":"skills_directory","type":"string","description":"Path to the skills directory to maintain and audit","required":true}]
outputs
[{"name":"maintenance_report","type":"string","description":"Maintained skills directory with updated names, unified terminology, repaired cross-references, and git commit documentation"}]
Skill Maintenance Ritual
I. The Workflow
This is a 9-step workflow for maintaining the skills directory.
Step 1: Recognize the Need for Maintenance
Goal: Identify when skill maintenance is needed.
Triggers:
User requests skill renames or refactors
You notice unclear or inconsistent skill names
New skills are added that reference outdated names
Terminology changes in the broader ecosystem (e.g., tool names, industry standards)
Periodic audit schedule (e.g., quarterly)
Actions:
Pause and clarify the scope with the user
Ask: What specifically needs to change?
Ask: What should stay the same?
Document the maintenance goal clearly
Output: Clear understanding of maintenance scope
Key Insight: Always pause and clarify scope before large refactors. Avoid over-refactoring by understanding what actually needs to change.
Step 2: Read Before Proposing
Goal: Understand what the skills actually do before suggesting changes.
Actions:
Read all skills that will be affected by the maintenance
Understand the actual purpose and workflow of each skill
Note any cross-references between skills
Identify patterns in naming or terminology
Tools:
file tool (read action) for each skill
Take notes on what each skill does
Output: Deep understanding of affected skills
Key Insight: Never propose renames or refactors without reading the actual content first. Names should reflect reality, not assumptions.
Step 3: Propose Clear, Descriptive Changes
Goal: Suggest changes that improve clarity and consistency.
Actions:
For renames: Propose names following the "verb-object" pattern
Key Insight: Comprehensive commit messages are documentation. Future maintainers need to understand why changes were made, not just what changed.
Step 9: Document the Process
Goal: Create summary documents for future reference.
Actions:
Create a summary document with:
Overview of changes
Refactoring strategy
Files modified
Benefits of the changes
Reflection on the process
Deliver summary to user with message tool
Tools:
file tool (write action)
message tool (result type)
Output: Documentation for future reference
Key Insight: Document the process immediately after completing it. Details fade quickly from memory.
Output
Renamed skill directories with updated name field and H1 heading in each SKILL.md
All cross-references updated to the new names or terminology
Zero stale references remaining (verified by grep)
A git commit with a structured message: what changed, why, what was preserved
Optional: a summary document delivered to the user if the scope was large
Examples
Scenario 1: "Rename zenflow-prompt to implementation-prompt and update all references" → Read the skill, propose the rename following verb-object pattern, execute directory mv + metadata update, grep for all cross-references, batch-edit and verify, commit with per-file replacement counts.
Scenario 2: "Deprecate old-pipeline skill — it's been replaced by batch-normalize-and-package" → Add a deprecated: true field to frontmatter, add a deprecation notice at the top of the body pointing to the replacement, update any skills that link to it, commit.
Edge Cases
User requests a rename but the new name is already taken by another skill — surface the conflict, propose a resolution, and get confirmation before executing
Terminology refactor touches historical documents (retrospectives, plans) outside the skills directory — catalog them but do not change them unless the user explicitly expands the scope
A skill has no cross-references in the rest of the directory — rename is safe; note this in the commit message
User wants to "clean up" a skill without changing its name — treat as in-place refactoring: read, propose specific changes, get confirmation, then edit
Anti-Patterns
Over-refactoring: Changing references that are contextually appropriate (e.g., tool-specific mentions in routing docs) because they happen to match the search term — always read the surrounding context before replacing
Proposing without reading: Suggesting renames based on the directory name alone without reading what the skill actually does — names should reflect reality, not assumptions
Relying on memory for references: Skipping grep and trusting recall to find all instances — always catalog systematically before refactoring
Vague commit messages: Writing "updated skills" without a per-file breakdown — commit messages are the only audit trail for future maintainers
