skill-recap

From a piece of work that is finished (or has reached a stopping point), identify reusable technical workflows / methodologies and distill them into new skills; also audit existing skills to see whether they need updating. This skill is the meta-skill that manages the skill system — it does not produce business documentation; it produces and maintains skills themselves.

When to use

Trigger when the user shows any of the following intents:

1. "Turn this / what I just did (X) into a skill" — explicit request to codify a workflow as a skill
2. "Check whether anything in this conversation should become a skill" / "Scan for anything reusable" — request to scan and mine
3. "Do any existing skills need updating?" / "Are any skills stale?" — request for an audit / maintenance
4. Do it all in one pass: "See what from this piece of work could be sedimented into skills, and also check whether existing skills need changes"

Typically invoked at the end of a piece of work (feature complete / milestone complete / before session end).

When NOT to use

This skill is about techniques, not about people. Distinguish it from adjacent skills before using:

Key boundary: This skill only distills "a set of reusable technical steps / methodologies" — about things. The user's personal working habits / thinking patterns (about people) are out of scope.

Do not use skill-recap for:

• Capturing the user's preferences or thinking style (those are about the person, not the workflow)
• Producing business / project documents (use the relevant business skill instead)

Output

A candidate report with two categories of items, each confirmed one-by-one with the user before any write:

A. New skill candidates

For each candidate provide:

• Name (kebab-case, deployed as <name>/SKILL.md under this repo's skills/; the name describes the skill itself, no plugin prefix needed)
• One-line positioning (what problem it solves, when it triggers)
• Distinction from existing skills (overlap with which one? Why is it a new skill rather than an extension of that one?)
• Outline (when to use / output / methodology key points / template skeleton)
• Reusability evidence (it showed up this time; why it will show up next time)

B. Existing skills needing update

For each provide:

• Target skill name
• Update type (stale-correction / missing additions / methodology evolution / trigger-word expansion)
• Specific update points (which section, change to what, why)
• Evidence (where in this conversation the need was exposed)

Methodology (6 steps; the core is "confirm each item")

1. Scan the conversation — identify "reusable workflow" signals

Walk back through the current conversation and find workflows that meet all three criteria:

• Recurring (not a one-shot operation; or even if one-shot, clearly a generic pattern)
• Has fixed steps (not improvised; a describable N-step process)
• Will be done again (still applies in a different scene / project)

Example signals:

• The user repeatedly asks for the same kind of output ("give me a comparison table", "generate a checklist", "produce a debugging doc")
• Claude repeatedly executes the same set of steps (read current state → compare → produce → verify)
• A debugging / triage pattern was proven effective (worth codifying)
• The user corrected Claude's approach (implying there should be a better standard flow)

🔭 Identify session-spanning high-level orchestration needs (easy to miss): The scan should not only focus on "what single-point actions were taken" but also on "session-spanning meta-needs". Signals: the user asks the same kind of question repeatedly (e.g. repeatedly asking "confirm it's clean / confirm nothing is missing"), the main line of work repeatedly executes the same orchestration, multiple single-point workflows are actually sub-steps of one larger workflow. These tend to be orchestration-layer skills (above single-point workflows) — focusing only on single points makes them easiest to miss. Example: above the single points of "legacy-code disposal" and "repository hygiene" there is the session-spanning "workspace-consistency check".

⚠️ Exclude one-shot content: Decisions that only serve this task, project-specific facts, and temporary workarounds are not distilled.

No self-immunity: skill-recap is a meta-skill, but it does not exempt itself — when the user invokes this skill, skill-recap itself is on equal footing with other skills and is included in step 4's "audit existing skills". A skill cannot self-trigger a "self-audit", but when the user invokes it, it can (and should) be treated as an audit target.

2. Generalize — strip the scene, distill the methodology

Abstract the workflow from "this specific scene" to "a general methodology":

• Strip: project names, specific technologies (e.g. MQTTS / WebRTC / Hilt), specific file names, specific constants
• Keep: step structure, judgment principles, output form, check dimensions, pitfall-avoidance points
• Demote examples to references: this scene becomes an appendix "Practical reference"; it does not enter the methodology body

Failure-signal check (required): If the methodology body (not the "Practical reference" appendix) contains domain-specific nouns — specific protocol-stack layers (e.g. "network → ICE → DTLS"), specific tool names (e.g. tcpdump / GStreamer), specific technology names — it means it has not been generalized enough. Move those nouns into the "Practical reference" appendix and replace them in the body with abstract referents (e.g. "the native observability signal of that layer", "the probe built into the peer environment").

Cross-domain paraphrase check (required): Restate each step in the vocabulary of a completely different domain (e.g. swap the WebRTC joint-debugging story for API integration / hardware-software coordination). Any step that does not make sense until you swap in another domain's terminology is still scene-bound and needs more abstraction.

Test: Apply the methodology to "another completely different scene" — does it still hold? If not, it is not generalized enough.

3. Dedup against existing skills — read existing skills, avoid duplication

Glob the SKILL.md of all available skills (including plugin skills and project standalone skills) + read each description / when-to-use, then compare against candidates:

• Fully covered? → Do not create; instead note in the report "already covered by skill X"
• Partial overlap? → Note on the candidate "overlaps with X on Y, differs on Z"; let the user choose (new / extend X / merge)
• Fully independent? → New skill candidate

Also scan all available skills (standalone skills in the project, or other skills the user mentioned) and dedup the same way.

4. Audit existing skills — did this conversation expose an update need?

Walk through each existing skill against this conversation:

• Stale: the workflow / convention the skill describes no longer matches current actual practice (e.g. decision reversed, workflow evolved)
• Missing: the skill omits an important dimension / step (exposed by a pitfall this time)
• Methodology evolution: a better approach emerged this time; the skill should be upgraded
• Trigger words insufficient: the user said something that did not trigger the corresponding skill (add trigger words)

5. Produce a report — candidate list, do not write

Output all candidates (new skills + skills needing update) in the "Output" format. Only output; do not write files.

6. Confirm each item, then write (red line: no silent writes)

• For each item ask the user: create / update / adjust wording / reject
• When a new skill candidate is confirmed, also choose its integration mode (see "Integration architecture decision" below)
• Writing-plan confirmation for complex / high-level candidates (intermediate step): For complex or high-level skill candidates, the report outline alone is not enough to authorize writing — first present a detailed writing plan (section structure + key points per section + design decisions requiring the user's call), then write after the user confirms the plan. So confirmation is two-tier: report-direction confirmation → writing-plan confirmation → write. Simple candidates can still be written directly after report-level confirmation.
• Only Write/Edit the corresponding skill file when the user has explicitly confirmed
• Reference sync: Before writing, if a new / changed skill references other skills ("relationship with other skills", integration links, etc.), verify the reference name matches the system's current actual name. The skill system evolves (renames / splits / merges); referencing by memory or old directory names will go stale and break links — use Glob/ls on the current skills directory to verify
• Do not write anything unconfirmed / rejected
• After writing, report: what was written, what the user rejected

Write authorization is per-skill: A skill may be written only when all of its revisions are agreed and there is no pending addition or correction. "Agreement in discussion" is directional approval and does not equal write authorization — writing must wait until the user explicitly says "write" for that skill. One skill's status does not affect others: A still being corrected does not block a finalized B from being written.

Integration architecture decision (chosen together with step 6 when confirming a new skill)

When step 6 confirms a new skill candidate that has methodological overlap or relationship with existing skills, also decide how it integrates into the existing skill system.

Four integration modes:

Link over copy (default ②): When two skills share methodology, default to a link (single source of truth) — copies drift (updates touch only one place), links take effect globally; only copy when both places genuinely need to evolve independently. Placement: the referencing side adds a one-line pointer (e.g. "X follows the discipline of the Y skill; not repeated here") and does not copy Y's content.

Phase 2: skill-recap self-revision (triggered after general updates are written)

skill-recap's methodology is not itself complete. No matter which skill's update this round produced, apply the shortcomings exposed during the skill-recap process that required additional user correction — places Claude was corrected, cases the methodology did not cover, wording / placement that went through repeated rework — all reflect gaps in skill-recap itself. These gaps only fully surface after the general skill-update discussion has run to completion, so self-revision is a separate Phase 2, not mixed into Phase 1.

Trigger condition: Phase 1 (6-step core + step-6 integration architecture decision) writes are complete.

Actions (reuse skill-recap's own methodology, closed loop):

1. Review this whole round; collect every "additional user correction" and every "the methodology didn't catch it" point
2. Treat each as a skill-recap self-revision candidate; produce a report (update point + evidence = which conversation spot exposed it this time)
3. Confirm item-by-item → write into skill-recap

Scan sufficiency (required): For each workflow segment (drafting-item wording / report / confirmation / write / integration architecture / self-revision) ask "was there friction or correction here"; do not conclude "no other gaps" from a single "I see nothing". For each gap that surfaces, attribute it by red-line 5's clarification, not by surface appearance of "looks like a behavior lapse".

Trigger method: After Phase 1 writes complete, automatically ask — "This application exposed N self-gaps in skill-recap; enter Phase 2 self-revision?" (do not rely on the user remembering to trigger).

Difference from step 4 "audit existing skills": step 4 happens before discussion and can only catch skill-recap content staleness (based on known information); Phase 2 happens after discussion and catches gaps exposed by application (which only occur during discussion). The two do not conflict.

Report template

## Skill recap report

### A. New skill candidates ({n})

#### Candidate 1: {name}
- **Positioning**: {one line, when it triggers, what it solves}
- **Distinction from existing skills**: overlaps with {X} on {Y}, differs on {Z}
- **Integration mode**: ① independent no reference / ② independent + linked from existing skill (default) / ③ extend into X / ④ merge
- **Outline**: when to use / output / methodology key points (3-5) / template skeleton
- **Reusability evidence**: shown this time at {conversation spot}, will be used next time at {scene}

#### Candidate 2: ...

### B. Existing skills needing update ({n})

#### Update 1: {skill name}
- **Type**: stale-correction / missing additions / methodology evolution / trigger-word expansion
- **Update point**: {which section} change to {what}, because {which conversation spot exposed it}
- **Proposed change summary**: {2-3 lines}

#### Update 2: ...

### C. Already covered by an existing skill (do not create new)

- {workflow description} → already covered by {skill name}; not re-distilled

---

Please confirm item-by-item: for each candidate / update reply "create / update", "adjust: ...", or "reject".
Unconfirmed items are not written.

Red lines (do not violate)

1. No silent writes — All new skills / updates must first be reported and confirmed item-by-item with the user; nothing unconfirmed is written to a file. Write authorization is per-skill (see step 6); "agreement in discussion" does not equal write authorization. Reasoning: the user is the only authority on what enters their skill library; silent writes break that trust and make the library unpredictable.
2. Do not distill one-shot content — Decisions / project facts / temporary workarounds that only serve this task are not distilled into skills. Reasoning: one-shot content has no reuse value and would pollute the skill library with low-leverage entries.
3. Do not skip generalization — Candidate skills must strip the scene (project / tech stack) so the methodology applies to other scenes; the methodology body must not contain domain-specific nouns (protocol-stack layers / tool names / technology names), and examples appear only in the "Practical reference" appendix; it must pass step 2's "failure-signal check + cross-domain paraphrase check" to count as generalized enough. Reasoning: scene-bound content fails the second time it is needed in a different project, which defeats the point of being a skill.
4. Do not skip dedup — Read existing skills and compare; fully covered → do not create new; partial overlap → let the user choose new / extend / merge. Reasoning: duplicate skills fragment the single-source-of-truth and confuse triggering.
5. Do not mix in behavioral preferences — The user's thinking / working habits are out of scope for this skill (this skill only handles technical workflows). But do not over-apply this: if a mistake's specific manifestation falls on a skill-recap workflow segment (drafting-item wording / report / confirmation / write / integration architecture / self-revision), it is a procedural rule rather than a behavioral preference and should be a skill-recap revision candidate.
6. Do not fabricate reusability — Candidates must be based on workflows that actually appeared in this conversation, with evidence; do not speculate "this might be useful". Reasoning: speculative skills bloat the library with entries that never trigger correctly.
7. Do not advance wording before understanding is precise — Before wording each proposed item, first restate "what it targets and how it differs from adjacent proposed items" to confirm the understanding is precise; if there is any doubt, ask the user first instead of filling in yourself. "Agree on direction" does not equal "understanding of that item is precisely confirmed". Reasoning: imprecise understanding produces wording that looks right but silently misses the point, and is hard to correct later.

Practical reference (optional, as an appendix illustration)

The methodology itself is fully generic. If the project already has a real instance of "distilling a reusable skill from a piece of work" (e.g. noticing that this session repeatedly executed a workflow → distilling it into a new skill), that distillation process can be used as an appendix illustration — recording what the scan found, how it was generalized, against which existing skill it was deduped, and how it was finally presented to the user for confirmation. But the methodology does not depend on any specific scene.

Follow-up actions after completion (suggest to the user; do not auto-execute)

• If a newly created skill is generic, suggest migrating it to the global ~/.claude/skills/ (cross-project)
• If multiple related skills were distilled, suggest establishing cross-references between them (skill A's "Distinction" section links to skill B)