# Skill Maintenance

> Skill Maintenance Ritual

- Skill: `dojogenesis/skill-maintenance` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dojogenesis/skill-maintenance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dojogenesis/skill-maintenance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Integrations & APIs
- Author: DojoGenesis (https://skillmd.com/u/dojogenesis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dojogenesis/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:**
```json
{
  "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