| 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:
.claude/skills/<skill_name>/SKILL.md (relative to repo root)
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_github_tasks 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:
- Immediately recognize this as a strong signal
- Propose updating the skill file
- Make the skill more explicit with numbered steps, examples, and emphasis on
the template
- 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:
- Complete the current task
- Mention to the user: "I should update the skill to document the cross-repo
TODO format. Should I do that?"
- 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:
- Complete the task with the new step
- Ask: "Should I update the skill to always include the 'Team: Data Platform'
label?"
- 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:
- After completing the task, ask: "Should I document this as a new skill so I
can follow it more precisely next time?"
- If yes, create
.claude/skills/<workflow_name>/SKILL.md with clear steps
- Add a reference to it in the root CLAUDE.md file
Related Documentation
