SuperAPI AI Directory

skill-update

Coding & development

View repository

Updated 11-05 16:17

About this skill

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:

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)