Skill Maintenance

Skill Maintenance Ritual

Philosophy

A skills directory is a living codebase. Names drift, terminology evolves, cross-references rot, and skills that were once clearly scoped start overlapping. Left unaddressed, these inconsistencies accumulate into a directory where an agent — or a human — cannot reliably find what they need or trust that what they find is current.

Maintenance is the practice of making that drift visible and reversible. The key discipline is: read before refactoring, catalog before replacing, and document the audit trail in the commit message so future maintainers can understand not just what changed but why.

When to Use

• User requests skill renames, refactors, or deprecations
• New skills are added that create naming conflicts or overlap with existing ones
• Terminology changes in the broader ecosystem (tool names, platform names, industry standards) make existing skill names confusing
• A periodic audit reveals stale cross-references or inconsistent naming
• A skill needs to be deprecated and replaced by a successor

Do NOT apply to in-flight work or to historical documents (retrospectives, plans) outside the skills directory unless the user explicitly expands scope.

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:

1. Pause and clarify the scope with the user
2. Ask: What specifically needs to change?
3. Ask: What should stay the same?
4. 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:

1. Read all skills that will be affected by the maintenance
2. Understand the actual purpose and workflow of each skill
3. Note any cross-references between skills
4. 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:

1. For renames: Propose names following the "verb-object" pattern
   • Examples: release-specification, implementation-prompt
2. For terminology refactors: Identify what should change and what should stay
3. Create a table showing old → new with rationale
4. Get user confirmation before proceeding

Tools:

• message tool (ask type) to propose and get feedback

Output: Agreed-upon changes

Key Insight: Good naming is good documentation. Descriptive names reduce cognitive load and make skills immediately understandable.

Step 4: Execute Renames Systematically

Goal: Rename skill directories and update internal references.

Actions:

1. Rename skill directories using mv command
2. Update name field in each SKILL.md frontmatter
3. Update title (H1 heading) in each SKILL.md
4. Verify renames with ls command

Tools:

• shell tool for directory renames
• file tool (edit action) for content updates

Output: Renamed skills with updated metadata

Key Insight: Rename both the directory and the internal metadata. Inconsistency between directory name and skill name causes confusion.

Step 5: Search and Catalog References

Goal: Find all instances of terminology or names that need updating.

Actions:

1. Use grep -r -i "<term>" to find all references
2. Count references by directory: grep -r -i "<term>" | cut -d: -f1 | sed 's|^\./||' | cut -d/ -f1 | sort | uniq -c | sort -rn
3. Identify which references need updating (skills directory) vs. which should stay (historical docs)
4. Confirm scope with user if needed

Tools:

• shell tool with grep for searching
• wc -l to count references
• cut, sort, uniq -c to categorize

Output: Catalog of references to update

Key Insight: Always catalog before refactoring. Understanding the scope prevents over-refactoring or missing references.

Step 6: Read Context and Determine Strategy

Goal: Understand which references should change and which should stay.

Actions:

1. Use match tool (grep action) to view references with context
2. Analyze each usage to determine if it should be updated
3. Create a refactoring strategy:
   • What should be replaced?
   • What should be preserved?
   • What replacement text should be used?
4. Document the strategy

Tools:

• match tool (grep action) with leading/trailing context

Output: Refactoring strategy document

Example Strategy:

• Replace "Zenflow prompt" → "implementation prompt"
• Replace "Zenflow" (as executor) → "implementation agent"
• Preserve "Zenflow" when listing multiple tools: "Zenflow, Claude Code, etc."
• Preserve "Zenflow" in routing decisions: "Zenflow: Strategic implementation"

Key Insight: Not all references should be changed. Preserve tool-specific references when contextually appropriate.

Step 7: Execute Refactor with Batch Edits

Goal: Update all references systematically using batch edits.

Actions:

1. For each affected skill file:
   • Create a list of find/replace pairs
   • Use file tool (edit action) with multiple edits
   • Set all: true to replace all occurrences
2. Verify changes with grep after each file
3. Keep a count of replacements per file

Tools:

• file tool (edit action) with multiple edits
• shell tool with grep to verify

Output: Updated skill files

Example Edit:

{
  "edits": [
    {"all": true, "find": "Zenflow prompt", "replace": "implementation prompt"},
    {"all": true, "find": "Zenflow", "replace": "implementation agent"}
  ]
}

Key Insight: Batch edits are more efficient than one-by-one replacements. Use all: true to replace all occurrences in a single operation.

Step 8: Verify and Commit

Goal: Ensure all changes are correct and commit with comprehensive documentation.

Actions:

1. Verify no unintended references remain: grep -i "<old term>" <directory>
2. Check git status: git status
3. Stage changes: git add skills/
4. Write comprehensive commit message:
   • Summary of changes
   • File-by-file breakdown
   • Rationale for changes
   • What was preserved and why
5. Commit: git commit -m "<message>"
6. Push to remote: git push origin main

Tools:

• shell tool with git commands

Output: Committed and pushed changes

Commit Message Template:

<Action> in skills directory

<Summary paragraph>

Changes:
- <file1> (<N> replacements)
  - <change 1>
  - <change 2>
  
- <file2> (<N> replacements)
  - <change 1>

Kept <term> only when:
- <context 1>
- <context 2>

<Rationale paragraph>

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:

1. Create a summary document with:
   • Overview of changes
   • Refactoring strategy
   • Files modified
   • Benefits of the changes
   • Reflection on the process
2. 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

Best Practices

• Read the skill body, not just the directory name. A directory named seed-converter might implement a workflow more accurately described as process-extraction. Names should reflect what the skill does, and you can only know that by reading it.
• Catalog before replacing. Run a grep across the directory before executing any rename or terminology change. The count and distribution of references tells you the true scope and prevents missed instances.
• Preserve contextually appropriate references. When a skill names specific tools for routing decisions (e.g., "use Zenflow for X, Claude Code for Y"), that reference should survive a terminology refactor even if the generic term changes elsewhere.
• Verb-object naming for skills. Prefer release-specification over release-spec-generator; process-extraction over process-to-skill. The verb signals what the skill does, the object signals what it operates on.
• Deprecation is a first-class operation. A deprecated skill should carry a deprecated: true frontmatter field and a top-of-body notice pointing to the replacement. Do not delete without a forwarding reference.
• Commit messages are the audit trail. Per-file replacement counts and rationale for what was preserved belong in the commit message body. Future maintainers will not have this conversation's context.

Quality Checklist

Before closing a maintenance session:

• Every renamed skill has both its directory name and name frontmatter field updated to match
• Every renamed skill's H1 heading matches the new name
• grep confirms zero remaining stale references in the skills directory
• Historical documents outside the skills directory were cataloged but left unchanged (unless user expanded scope)
• Deprecated skills have deprecated: true in frontmatter and a top-of-body notice pointing to the replacement
• Git commit message includes: summary, per-file change counts, what was preserved and why
• User confirmed proposed changes before execution (no silent refactors)

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

Related Skills

• skill-creation — for creating new skills that will enter the directory being maintained
• process-extraction — for formalizing the maintenance workflow itself into a repeatable skill
• batch-normalize-and-package — for bulk normalization of community-sourced skills before adding them to the directory
• normalize-community-skill — for normalizing a single community skill to house standards before placement