From skills-maintenance
Use this skill when updating, improving, or maintaining existing Claude Code agent skills. Activates when the user asks to update, refactor, improve, or fix an existing skill. Does NOT activate for creating new skills from scratch.
npx claudepluginhub nsheaps/ai-mktpl --plugin skills-maintenanceThis skill uses the workspace's default tool permissions.
This skill helps you systematically maintain, update, and improve existing Claude Code agent skills. Use this when modifying skills that already exist, not for creating new ones.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Retrieves current documentation, API references, and code examples for libraries, frameworks, SDKs, CLIs, and services via Context7 CLI. Ideal for API syntax, configs, migrations, and setup queries.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
This skill helps you systematically maintain, update, and improve existing Claude Code agent skills. Use this when modifying skills that already exist, not for creating new ones.
✅ Activate when:
❌ Do NOT activate when:
Before making changes, thoroughly understand the existing skill:
Read the skill file (usually skills/skill-name/SKILL.md)
Review the frontmatter metadata:
name: Skill identifierdescription: When and how the skill activatesexamples (if present): Usage patternsAnalyze the skill content:
Check related files:
.claude-plugin/plugin.json)Common maintenance tasks:
Documentation Updates:
Behavioral Improvements:
Structure Refinements:
Version Updates:
plugin.json following semverFollow these principles when updating skills:
Frontmatter Rules:
---
name: skill-name # Lowercase, hyphen-separated, matches directory name
description: Clear description of when and how the skill activates (1-2 sentences)
examples: # Optional but recommended
- "Example trigger phrase 1"
- "Example trigger phrase 2"
---
Content Structure:
Writing Style:
When updating skills, refer to these authoritative sources:
📚 Primary Documentation Sources:
Claude Code Documentation: https://code.claude.com/docs
Claude Code on the Web: https://code.claude.com/docs/en/claude-code-on-the-web
Anthropic Documentation: https://docs.anthropic.com
Claude Code SDK Documentation: https://github.com/anthropics/claude-code-sdk
Claude Code GitHub Action: https://github.com/anthropics/claude-code-action
Claude Cookbook (Anthropic): https://github.com/anthropics/anthropic-cookbook
When to Reference Each:
Before finalizing updates:
Validate Syntax:
Test Activation:
Verify Behavior:
Check Integration:
After making changes:
Update plugin.json:
{
"name": "skill-name",
"version": "1.1.0", // Increment according to semver
"description": "Updated description if needed"
}
Versioning Rules:
Update README.md:
Update Marketplace Metadata:
## When to Use This Skill
**Original:**
- User asks to "commit changes"
**Updated:**
- User asks to "commit changes"
- User asks to "create a commit"
- User says "make a commit"
- Development task is complete and changes need committing
## What This Skill Does
**Original:**
Analyzes staged changes and creates a commit message.
**Updated:**
Analyzes staged and unstaged changes, suggests which files to stage, creates semantic commit messages following repository conventions, and handles multiple logical changes with atomic commits.
## Examples
**Original:**
Use this skill to commit your changes.
**Updated:**
**Example 1: Simple Feature Commit**
User: "Commit these changes"
Claude:
- [Analyzes changes]
- [Creates commit: "feat: add user authentication"]
**Example 2: Multiple Changes**
User: "Commit my work on the API and tests"
Claude:
- [Analyzes changes]
- [Creates commits:]
- "feat: add user API endpoints"
- "test: add API endpoint tests"
If a skill activates too broadly or too narrowly:
## Activation Conditions
**Too Broad (activates on everything):**
description: Use this skill for git operations
**Too Narrow (never activates):**
description: Use this skill when user says exactly "please create git commit now"
**Just Right:**
description: Use this skill when the user requests to commit changes, create commits, or when a development task is complete and code changes are ready to be committed. Activate during git workflow discussions.
Skills are instructions for Claude, not user documentation:
❌ User-facing: "This is a skill that helps you commit code." ✅ Claude-facing: "Activate when user requests to commit changes. Analyze staged files, generate semantic commit message, execute git commit."
Don't just say "use tools" - specify which ones:
❌ Vague: "Use the appropriate tools to complete the task."
✅ Specific: "Use the Bash tool to run git status and git diff. Use the Read tool to analyze changed files. Use the Edit tool if commit message preview is requested."
Help Claude know when NOT to use the skill:
## When NOT to Use This Skill
- User is just asking about git (use general knowledge instead)
- User wants to learn git commands (provide explanation, don't execute)
- No changes to commit (inform user, don't force empty commit)
- User is viewing history (use different skill or tools)
## Special Situations
**Large Changesets:**
- If more than 20 files changed, ask user which to commit
- Don't create massive commits without confirmation
**Sensitive Files:**
- Always exclude .env, credentials, secrets from commits
- Warn user if sensitive patterns detected
**Merge Conflicts:**
- Don't auto-commit during merge conflicts
- Guide user through resolution first
Help Claude understand the ecosystem:
## Related Skills
- `smart-commit` skill: Use for automatic committing during development
- `pr-description` skill: Use after committing to create PR descriptions
- `/commit` command: Alternative manual commit interface
Diagnosis:
Fix:
Diagnosis:
Fix:
Diagnosis:
Fix:
Diagnosis:
Fix:
Before finalizing skill updates, verify:
plugin.json according to semverKeep these handy when maintaining skills:
- Claude Code Docs: https://code.claude.com/docs
- Claude Code Web: https://code.claude.com/docs/en/claude-code-on-the-web
- Anthropic Docs: https://docs.anthropic.com
- Claude Code SDK: https://github.com/anthropics/claude-code-sdk
- GitHub Action: https://github.com/anthropics/claude-code-action
- Claude Cookbook: https://github.com/anthropics/anthropic-cookbook
- JSON Schema for settings: https://json.schemastore.org/claude-code-settings.json
User Request: "Update the smart-commit skill to handle merge commits better"
Your Workflow:
Read plugins/commit-skill/skills/smart-commit/SKILL.md
Identify current merge commit handling (or lack thereof)
Research merge commit best practices in Claude Cookbook
Update skill with new merge commit section:
## Handling Merge Commits
When changes include merge commits:
- Detect merge commit by checking git status for merge branch
- Ask user if they want to create merge commit or abort
- Use `git commit --no-edit` for standard merge messages
- Or allow custom merge message if user requests
Add example to documentation
Update plugin.json version from 1.0.0 to 1.1.0 (minor change)
Update README.md with merge commit feature
Test by simulating merge scenario
Commit changes with appropriate message
Result: Skill now handles merge commits gracefully, documentation is clear, version properly bumped.
Happy maintaining! 🛠️