# Skill Update

> Plan and apply changes to an existing skill in one workflow. Reads a skill-review report (bulk or deep-dive) or inline findings, drafts an edit list with the agent's recommended answer attached, walks the edits one at a time, applies them, and re-runs lint and frontmatter checks. Use after skill-review when you're ready to ship the changes. Trigger on "apply the review", "update this skill", "fix the skill", "ship the recommendations", "edit this skill", "apply the plan", "implement the changes".

- Skill: `ivy00johns/skill-update` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ivy00johns/skill-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivy00johns/skill-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ivy00johns (https://skillmd.com/u/ivy00johns)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ivy00johns/skill-update

---


# Skill Update

Plan and apply changes to an existing skill in a single walk-through. Consumes a review report (or inline findings), drafts one edit per bullet with the agent's recommended answer attached, walks the edits one at a time, applies them, and re-validates the skill.

## When to Use

- A `skill-review` report exists and the user wants next steps
- The user said something like "apply the review", "ship the recommendations", "fix this skill"
- A short list of fixes is in the chat and the user wants them applied with confirmation
- Simple direct edits where planning and applying is one motion, not two

If there is no review yet, run `skill-review` first and come back.

## Inputs

- **Review source** — a `skill-review` report (single-skill or `--scope=all`), or inline findings from chat
- **Target skill(s)** — SKILL.md path(s) to edit
- **Scope (optional)** — priority levels to walk ("just P0", "P0 and P1", "all")

## Process

### Step 1: Parse the Feedback

Read every report and note provided. Extract:

- Each issue with its severity, affected skill, file, and dimension
- Each recommendation
- Trigger-testing results and coverage gaps from `skill-review`

Deduplicate — if the same issue surfaces from both a bulk pass and a deep-dive review, merge them. Group by category:

| Category | Examples |
|----------|----------|
| Frontmatter fixes | Missing fields, wrong types, bad version |
| Description rewrites | Vague triggers, missing keywords, too long/short |
| Content restructuring | Body too long, needs reference extraction, missing sections |
| Instruction improvements | Ambiguous steps, missing rationale, wrong voice |
| Ownership fixes | Overlaps, stale `composes_with`, missing declarations |
| New content | Missing reference files, examples, checklists |
| Deletions | Duplicate content, orphan files, dead links |

### Step 2: Draft the Edit Plan

Produce a one-bullet-per-edit list. Each bullet carries an explicit **recommended answer** so the user can accept by nodding.

Score each change:

- **Impact** (1–3): 3 = skill misfires without this, 2 = quality suffers, 1 = polish
- **Effort** (1–3): 1 = quick field edit, 2 = rewrite a section, 3 = major rework

Sort by Impact DESC, then Effort ASC. P0 first, P1 next, P2/P3 later.

For each bullet, draft the actual edit text — not "improve the description" but `Rewrite description to: "<new text>"`. For description rewrites, draft the new description in the plan so it can be applied verbatim.

See `references/plan-format.md` for the full bullet schema.

### Step 3: Walk the User Through Edits

Present the plan, then walk one edit at a time. For each:

1. State the change — file, what, why, recommended answer
2. Ask: "Apply this edit?" Default is yes
3. On confirm, apply with `Edit` (one logical change per call — never batch unrelated edits)
4. On skip, note why and move on
5. On modify, take the user's revision and apply that
6. Briefly confirm: `Updated <skill-name>: <what changed>`

Rules while applying:

- **Read before editing, always** — never edit a file you have not read this session
- For new reference files, create the file first, then edit the parent SKILL.md to link it
- For deletions, update any links that pointed to the removed content
- Preserve YAML formatting and field order in frontmatter edits
- If a planned edit no longer makes sense (file already fixed, context changed), skip it and say why

For batches of 10+ independent edits across different skills, parallel-dispatch with subagents.

### Step 4: Post-Edit Validation

After all edits in this pass:

- Re-read every modified SKILL.md and validate frontmatter against `skills/meta/skill-writer/references/frontmatter-spec.md`
- Confirm body length is within spec guidance — ≤5,000 words and ≤500 lines (soft warnings); when content could move to references, prefer that over inflating the SKILL.md body
- Resolve all reference links in modified files
- If `owns` fields changed, re-check there are no overlaps with other agent roles
- Run markdownlint if available — `.markdownlint.json` is at repo root

See `references/validation-checklist.md` for the full check list and report format.

### Step 5: Re-Run Review and Sync (optional)

Offer:

> "Re-run `skill-review` to confirm the issues are gone? I can diff before/after."

Then offer sync:

> "All changes applied and validated. Sync to your global skill locations now?"

If yes, invoke `sync-skills`:

```bash
skills/workflows/sync-skills/scripts/sync-skills.sh --to-all
```

If declined, remind: "Repo versions are updated but your global locations still have the old versions — sync when you are ready."

## Error Handling

- **Edit fails:** report what failed, skip to the next edit, collect failures, present them at the end with retry/manual-fix/skip options
- **Validation fails:** name the specific failures, suggest fixes, ask whether to fix now or leave for later — do not auto-fix without confirmation

## Guidelines

- Be specific in every bullet — vague "improve the description" is not actionable
- Attach the recommended answer to every bullet so the user can accept fast
- One logical change per `Edit` call
- Skip pure style preferences — focus on functional improvements
- Note ordering dependencies between changes (e.g. ownership fix in skill A must land before skill B's update)
- Never reformat an entire file as a side-effect of a targeted edit

## Data source

Before drafting the edit list, consult real usage signal: run
`scripts/skill-health.sh report --json` (P2-C skill-health telemetry) for the
skills you are about to change. It reports per-skill total invocations,
7-day/30-day success rates, a `declining` flag, and version drift (recorded vs
current `SKILL.md` frontmatter `version`). The math is deterministic in code,
never a prompt. The signal is coarse and best-effort — the emitter records
`outcome:unknown` and a `no-data` skill is merely unobserved, not broken — so use
it to prioritize and justify edits, not to fabricate problems. A `stale`
version-drift row is a strong, signal-free hint that a skill's recorded behavior
lags its current definition. See `contracts/installer/skill-health.md`.

## References

- `references/plan-format.md` — schema for the one-bullet-per-edit plan
- `references/validation-checklist.md` — post-edit checks (markdownlint, frontmatter spec, line count, broken xrefs)