| name | update-skill |
| description | Use when revising one or more existing Claude Code skills, aligning skill instructions with current repository policy, narrowing overlapping ownership, or applying a deliberate behavior change without creating a competing skill. |
| model | opus |
| context | fork |
| allowed-tools | Bash, Task, Read, Glob, Edit, MultiEdit, TodoWrite |
| argument-hint | [skill specifier] [--changes=...] |
Update Skill
Boundaries
- Update existing skill behavior and documentation; use
create-skill when no
suitable owner exists.
- Preserve established public behavior unless the requested change explicitly
removes or reassigns it.
- Do not modernize unrelated skills merely because they are nearby.
Follow ${CLAUDE_SKILL_DIR}/../../constitution/references/authoring-invariants.md.
The current skill and its real callers are authoritative; the template is a
concise aid, not a migration target whose headings must be copied.
Inputs
- Required: a path, plugin-qualified skill name, glob, or explicit
--all.
- Optional: requested behavior, trigger, wording, or policy changes.
- Never interpret an empty selector as permission to update every skill.
Workflow
- Resolve the selector and list exact targets. Reject ambiguity before edits.
- Read each target completely, including directly referenced files and real
cross-skill invocations.
- Define current ownership and the requested end state. Conduct a paper-only
thought experiment and blindspot test over positive and near-miss cases for
changed triggers or behavior. If notes are written down, keep them temporary
as a Markdown scratch document in an OS temp
folder (for example
${TMPDIR:-/tmp}/check.md) using
${CLAUDE_SKILL_DIR}/../../constitution/references/check.md as the
example table format with :white_check_mark:/:x: status markers,
and delete them before staging; they are not deliverables and must not be
committed.
- Capture a failing baseline for testable behavior when a deterministic check
exists, then rewrite the existing document coherently. Remove superseded
instructions and stale references.
- Keep the core workflow concise; move only genuinely conditional bulk to
references. Do not add personas, diagrams, fixed phases, or delegation
ceremony unless they materially clarify this particular skill.
- Validate each affected plugin and run repository policy checks.
- Re-run the thought experiment and blindspot test for relevant functional and
trigger behavior. Fix identified blindspots without widening the requested
scope. Do not claim runtime behavior was exercised unless an executable
evaluation actually ran.
Independent targets may be delegated in bounded batches — at most 8 skills per
batch and 8 parallel Task calls per dispatch. Each assignment must name exact
paths and constraints; review the combined diff afterward.
Verification
claude plugin validate --strict <plugin-path>
python3 "${CLAUDE_SKILL_DIR}/../verify-skill/scripts/quick_validate.py" <target>
Use governance:verify-skill for functional and trigger evaluation with
fix: true; in bulk updates bound the loop to 2 fix iterations per skill,
record remaining issues, and continue to the next target.
Completion
Report updated skills, ownership changes, validation results, thought-experiment
and blindspot coverage, runtime evaluation status (including "not exercised"),
and unresolved ambiguity. Confirm temporary Markdown thought-experiment notes
were deleted before commit. Never claim a bulk update without listing its
targets.
