Tool Sp Maintain Skills

Maintain Skills

Purpose

Guide the agent through a short maintenance workflow so project skills stay aligned with current repo behavior, branch changes, and skill-authoring standards instead of drifting into stale commands, stale examples, or missing coverage. Keep project guidance simple by giving each rule one clear home when maintenance reveals duplication or misplaced detail.

When to use this skill

• Repo commands, package-manager choices, workflows, or folder structure changed.
• A branch introduced new domains, libraries, or tooling that the current skills do not mention.
• Existing skills may still describe old commands, old package managers, or renamed features.
• The skill catalog changed and the top-level routing may need a corresponding refresh.

Scope boundaries

This tool maintains the existing skill catalog: what drifted, what duplicates what, which skill should own a rule. It is a catalog-level pass, not a single-file edit and not an authoring guide.

• tool-sp-create-skill — when the change genuinely needs a new skill rather than an update to an existing one. Deciding between the two is this tool's job; executing the creation is that one's.
• tool-sp-make-skill-shareable — when the question is one skill's portability rather than the catalog's freshness.
• tool-sp-maintain-agents-instructions — when the drift is in AGENTS.md, GEMINI.md, or .claude/CLAUDE.md rather than in the skills. The two hand off to each other: renaming a skill usually drifts both.
• ref-sp-agents-skills-authoring — the quality bar this tool checks against.
• ref-sp-agents-shareable-skills — the sharing spec and its validator, including the plugin-manifest check that catches a skill this pass renamed or re-scoped.

First Step

Read the repo's skill-authoring skill (ref-sp-agents-skills-authoring here, the requires dependency) before planning updates. If the maintenance pass touches skill quality, evals, scripts, or copied guidance, also read that skill's quality-evaluation reference (in this repo, its references/quality-evaluation.md).

Core Workflow

1. Inspect the current skill catalog and the change surface that might have invalidated it.
2. If the repo is on a feature branch or has local changes, inspect the branch diff first and treat it as the primary signal for what skill guidance may have drifted.
3. Map changed code, workflows, commands, and directories to the skills that should describe them.
4. Update only the affected skills, metadata, supporting references, and top-level routing that actually drifted.
5. If you discover repeated or misplaced guidance, consolidate it into the correct owner instead of copying the same fix across multiple skills.
6. Run the portable skill validator and address real findings in the touched or drifted skills.
7. Validate trigger quality, file diagnostics, and skill discovery before concluding.

Defaults

• Prefer a branch-diff-driven review over a blind rewrite of the entire skill catalog.
• Prefer updating the owning skill rather than adding top-level instruction detail that duplicates it.
• Prefer focused edits to the affected skill and its support files over sweeping rewrites.
• Prefer consolidating duplicated guidance into one owner instead of preserving near-copies across several skills.
• When the branch adds a new domain, decide whether an existing skill should expand, a new skill should be created, or the change is too repo-specific to generalize.
• When a maintenance pass reveals repeated eval failures or repeated helper-code recreation, promote the durable fix into the owning skill as a default, gotcha, validation rule, or scripts/ helper.
• If no skill update is actually needed, say so explicitly and explain why the current skill set still covers the change.

Wizard Questions

Ask only the questions that remain unanswered after inspecting the repo and branch.

Branch-Diff Guidance

• If git history is available, inspect changed files before editing skills.
• Prefer the narrowest useful diff: current branch against its base, current branch against the default branch, or local uncommitted changes when that is the only signal available.
• Treat changed commands, package-manager choices, workflow files, and new top-level directories as strong evidence that one or more skills may be stale.
• If a branch changed implementation but not the durable workflow, say that no skill update is needed instead of forcing one.

Gotchas

• Do not refresh every skill just because one area changed.
• Do not leave AGENTS.md or equivalent routing files stale after adding or renaming a skill.
• Do not leave the plugin manifest stale either. If the repo publishes a plugin, adding, removing, renaming, or re-scoping a skill changes what ships: a renamed folder leaves a dangling entry that silently drops from the published plugin, and a skill demoted to repo-local while still listed leaks to the world on the next release.
• Do not preserve copied examples, commands, or package managers that no longer match the repo.
• Do not create a new skill when an existing skill can absorb the change cleanly.
• Do not mutate shareability metadata casually; if a skill becomes repo-local or gains hard dependencies, record that intentionally.

Validation

• Check the result against ./references/checklist.md.
• If guidance moved between skills or out of top-level instructions, check ./references/consolidation-checklist.md too.
• Run the skill-authoring skill's validator (ref-sp-agents-skills-authoring; in this repo, node .agents/skills/ref-sp-agents-skills-authoring/scripts/validate-skill.mts <skill-dir>) for touched skills, or add --all on the skills root for the whole catalog (needs Node >= 22). For sharing-spec conformance, also run the sharing-spec validator owned by ref-sp-agents-shareable-skills (here, node .agents/skills/ref-sp-agents-shareable-skills/scripts/validate-sharing.mts .agents/skills --all).
• If output-quality evals produced grading.json files, summarize them with the skill-authoring skill's aggregation script (in this repo, .agents/skills/ref-sp-agents-skills-authoring/scripts/aggregate_eval_results.py <eval-workspace>).
• Run a targeted error check on the touched skill files.
• Run the repo's skill-discovery or catalog-validation command when one exists.
• Confirm that new or renamed skills are reflected in top-level routing if needed.
• If the maintenance pass decided that no updates were necessary, confirm that conclusion against the actual diff rather than intuition.

References

• Read ./references/consolidation-checklist.md when the maintenance pass reveals duplicated or misplaced guidance.
• Use the repo's instruction-maintenance skill (tool-sp-maintain-agents-instructions here) when skill changes imply drift in AGENTS.md, GEMINI.md, or .claude/CLAUDE.md.
• Use the repo's local-tasks skill (ref-sp-agents-local-tasks here) when the repo uses .agents/tasks/ to keep a local maintenance plan or artifact trail.
• Read the skill-authoring skill's quality-evaluation reference (ref-sp-agents-skills-authoring; in this repo, its references/quality-evaluation.md) when reviewing important skills against a stricter quality bar.
• Read ./references/checklist.md for a quick maintenance review pass.
• Read ./assets/trigger-eval-queries.example.json when testing trigger quality for branch-aware skill maintenance prompts.
• Review ./evals/evals.json when validating output quality for change-to-skill mapping and maintenance decisions.