maintain-skill-files

name	maintain-skill-files
description	Proactively update SKILL.md files when they become outdated, incorrect, or need improvements. Use when you notice a skill doesn't match current workflow, when user corrects your skill usage, or when discovering better practices that should be documented.

Skill: Maintain Skill Files

Overview

This skill defines when and how to proactively update SKILL files to improve future interactions.

Core principle: If you notice that a skill needs updating, offer to update it immediately. Don't wait for the user to ask.

When to Update Skills

Watch for these signals that a skill needs updating:

Strong signals (update immediately):

• You notice the skill is outdated - Commands, file paths, or processes have changed
• You didn't follow the skill correctly - If the user points out you missed steps or didn't follow the documented workflow
• User complains a skill wasn't triggered - If the user says you should have used a skill but didn't, check if the skill has proper YAML frontmatter with name: and description: fields (see "Skill Format Requirements" below)
• User corrects your behavior on a workflow - When the user says "actually, you should do X instead of Y" for a process that has a skill
• User adds new requirements or steps - The user teaches you additional steps that should be part of the workflow
• User expresses frustration about a repeated workflow - Phrases like "I'm annoyed that...", "you still...", "again...", "why do I have to..."
• Instructions are ambiguous - If you misunderstood a skill's instructions, make them clearer

Moderate signals (consider updating):

• You discover edge cases or gotchas - While following a skill, you encounter situations not covered in the documentation
• User shares tips or tricks - Additional context that makes following the workflow easier

When NOT to update:

• One-off corrections that don't apply to the general workflow
• Temporary workarounds
• Information that's likely to change frequently
• Details that are already well-documented in the skill

What Makes a Good Skill

Skills are specific, repeatable workflows or procedures. Create or update skills for:

• Multi-step processes that are done regularly
• Workflows with specific requirements or gotchas
• Procedures that need to be followed precisely
• Tasks that have a clear start and end state

Location: /Users/ageiduschek/src/pulse-data/.claude/skills/<skill_name>/SKILL.md

When to create a NEW skill:

• The workflow is distinct from existing skills
• It's referenced or used frequently enough to warrant its own documentation
• It has enough complexity that step-by-step instructions are valuable
• The user has performed this multi-step process multiple times

When to UPDATE an existing skill:

• User points out you didn't follow the skill correctly
• User adds new requirements or steps
• You discover edge cases or gotchas
• Instructions are ambiguous and led to mistakes
• Commands or paths are outdated

How to Update a Skill

Step 1: Identify what needs updating

When you notice a signal from the "When to Update" section, immediately consider:

• Which skill should be updated (or should a new one be created)?
• What specific information needs to be added/changed?
• Will this help prevent similar issues in the future?

Step 2: Propose the change

Tell the user what you want to update and why. For example:

"I notice you had to correct me about using the issue template. I should update the create_recidiviz_data_issues skill to make that more explicit. Would you like me to do that?"

OR if it's very obvious:

"I'm going to update the skill to include this step since it's part of the workflow."

Step 3: Make the update

• Use the Edit tool to update existing skill files
• Use the Write tool to create new skill files
• Be clear and specific in the documentation
• Include examples when helpful
• Use formatting (headers, bullets, bold) to make it scannable
• Follow the skill file structure (Overview, When to Use, Steps, etc.)

Step 4: Verify the update

After updating:

• Briefly tell the user what you updated
• Mention how it will help in the future

Best Practices for Writing Skills

For official best practices on writing SKILL files, see the Skills documentation.

Skill Format Requirements

CRITICAL: All skills MUST have YAML frontmatter with name: and description: fields. This is how Claude autonomously discovers when to use skills.

Required format (from official docs):

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it. Use when [specific trigger phrases].
---

Requirements:

• name: Lowercase letters, numbers, and hyphens only (max 64 characters)
• description: Max 1024 characters. Must include:
  • What the skill does
  • When Claude should use it (include specific trigger terms like "file", "create", "update", etc.)

Example:

---
name: create-github-tasks
description: File GitHub issues and tasks. Use when the user asks to file, create, or track issues, tasks, tickets, or TODOs.
---

When updating skills: If a skill doesn't have this frontmatter, or if the user complains the skill wasn't triggered, add or improve the YAML frontmatter with clear trigger terms in the description.

Example Scenarios

Scenario 1: User corrects you multiple times

Signal: User says "I'm annoyed that you still needed to be prompted to follow the issue template structure"

Action:

1. Immediately recognize this as a strong signal
2. Propose updating the skill file
3. Make the skill more explicit with numbered steps, examples, and emphasis on the template
4. Tell the user you've updated it

Scenario 2: You discover edge cases

Signal: While following the "create GitHub task" skill, you discover that if the task is for a different repo, the TODO format is different

Action:

1. Complete the current task
2. Mention to the user: "I should update the skill to document the cross-repo TODO format. Should I do that?"
3. If yes, add a section or step about cross-repo TODOs with examples

Scenario 3: User adds new steps

Signal: User says "Also make sure to add the 'Team: Data Platform' label"

Action:

1. Complete the task with the new step
2. Ask: "Should I update the skill to always include the 'Team: Data Platform' label?"
3. If yes, add this as a step in the workflow

Scenario 4: User teaches you a new workflow

Signal: User walks you through a complex multi-step process that you'll likely do again

Action:

1. After completing the task, ask: "Should I document this as a new skill so I can follow it more precisely next time?"
2. If yes, create .claude/skills/<workflow_name>/SKILL.md with clear steps
3. Add a reference to it in the root CLAUDE.md file

Maintaining the Skills List

When you create a new skill, remember to update the "Available skills" section in the root CLAUDE.md file with a link to the new skill.

Related Documentation

• Main CLAUDE.md - The root documentation file
• Create Recidiviz Data Issues - Example of a well-structured skill