Extract Best Practices

Extract Best Practices — Session Pattern Mining

Mines the current session — not an overlay, not a file — for repeatable patterns nobody explicitly flagged, and turns the genuinely reusable ones into real, dispatchable skills or agents. Nothing is authored, edited, or posted anywhere without explicit approval at the relevant checkpoint.

When to use

• You notice you performed the same multi-step workflow more than once this session, and never ran /ievo:evo on it
• You're wrapping up a session and wondering "should any of this become a skill?"
• You hit the same error and recovered the same way more than once
• You explicitly invoke /ievo:extract-best-practices

When NOT to use — related but different tools

This skill's job ends where those begin: it finds patterns nobody captured yet, then hands off to the tool that actually owns writing (/ievo:evo for a lesson, this skill's own Phase 4 for a new package).

Phase Overview

Phase 1 — Mining          Scan the session for repeatable patterns
Phase 2 — Cross-check     Match against installed skills/agents
Phase 3 — Proposal        Classify + propose disposition   [CHECKPOINT 1]
Phase 4 — Authoring       Write new packages, or hand off to /ievo:evo  [CHECKPOINT 2]
Phase 5 — Upstream        Optional: offer to share a new package upstream
Phase 6 — Report          Summary table

Phase 1: Mining

Reason over the current session's own context — the conversation so far, not a transcript file or session log path. This is the same portable approach /ievo:handoff Step 2 uses to gather "what this session did": no host-specific file format to assume, works identically on any agentskills.io platform.

Look for three pattern shapes:

• Procedure — a multi-step workflow performed more than once, or performed once but unambiguously general and non-trivial ("do A → B → C whenever X happens").
• Judgment / decision framework — a recurring reasoning rule applied more than once ("whenever X, prefer Y because Z", a review stance requiring its own context).
• Error-recovery pattern — a specific failure and its fix, repeated or clearly reusable beyond this one incident.

Threshold: seen 2x in this session, OR clearly reusable from a single occurrence (a well-defined, non-trivial, generalizable procedure doesn't need to repeat to qualify — matching the source anti-pattern this skill is built to respect, see Anti-Pattern Detection below). This is a judgment call, not a mechanical count — the same lightweight style consolidate/SKILL.md Step 4 and evo/SKILL.md Step 5.7 use for cluster detection: no sub-agent dispatch, no fixed entry-count threshold beyond this floor.

Do NOT flag:

• One-off tasks with no reuse signal
• Project-specific trivia with no generalizable shape
• Anything already captured this session via /ievo:evo (that's what it's for — this skill exists for what was never flagged, not to duplicate a capture that already happened)

If nothing qualifies: report Nothing to extract — no repeated or clearly-reusable patterns found this session. and stop. No checkpoints, no writes.

Phase 2: Cross-check against installed skills/agents

Enumerate what's already installed, same client-gated target set evo/SKILL.md Step 1 matches lesson targets against (detect the invoking client once per /ievo:init Step 1.5, ordered: $CLAUDECODE set with $CODEX_CLI unset → Claude Code, else $CODEX_CLI set → Codex, else a Codex Desktop signal (CODEX_INTERNAL_ORIGINATOR_OVERRIDE=Codex Desktop, or macOS __CFBundleIdentifier=com.openai.codex) → Codex, else Claude Code; same rule):

On Claude Code (Step 1.5: no Codex signal) — project-level (preferred):

• .claude/skills/*/SKILL.md, .claude/agents/*.md
• .claude/plugins/*/skills/*/SKILL.md, .claude/plugins/*/agents/*.md

On Claude Code — user-level (fallback):

• ~/.claude/skills/*/SKILL.md, ~/.claude/agents/*.md
• ~/.claude/plugins/*/skills/*/SKILL.md, ~/.claude/plugins/*/agents/*.md

On Codex (Step 1.5: $CODEX_CLI set, or a Codex Desktop signal) — skills only:

• .agents/skills/*/SKILL.md (project-level, preferred), ~/.agents/skills/*/SKILL.md (user-level fallback) — Codex documents no project-level custom-agent path, so there is no agent set to cross-check on Codex

For each pattern from Phase 1, check whether an existing skill/agent's description (and, if ambiguous, its body) already covers it. This feeds Phase 3's disposition call — it does not itself write or propose anything.

Phase 3: Proposal [CHECKPOINT 1]

Step 3: Classify shape

For each pattern, classify using the same three-way vocabulary consolidate/SKILL.md entry-cluster mode Step 3 applies to overlay entries, adapted to session-observed patterns:

• Procedure → candidate shape: skill
• Judgment / decision framework → candidate shape: agent
• Mixed → candidate shape: skill+agent pair

Fold error-recovery patterns into whichever shape their content resembles: a specific recovery sequence → skill; a general "when X fails, reason about Y" stance → agent.

Step 4: Propose disposition

Using Phase 2's scan, propose one of three dispositions per pattern:

• Option A — Extract to a new skill/agent(/pair): no existing coverage, and the pattern is clearly general and reusable beyond this project.
• Option B — Route to /ievo:evo: covers two cases — (a) the pattern is real but too narrow or project-specific to stand alone, or (b) an existing skill/agent already covers the general shape and this session surfaced a refinement, gap, or extension of it. Either way, /ievo:evo already does its own target/scope classification (project-wide vs. the specific skill/agent this refines) in its own Step 1 — this skill does not pre-resolve that, it just hands off.
• Option C — Skip: on reflection, no reuse signal despite passing Phase 1's rough filter (e.g. it turns out to be genuinely one-off).

CHECKPOINT 1

Present every candidate via AskUserQuestion, batched up to 4 per call (same batching feedback/SKILL.md Step 1b uses for multiple structured questions), each with its proposed disposition and a one-line rationale:

• Question: <pattern summary> — <proposed disposition>. Proceed?
• Header: <short tag, max 12 chars>
• Options (single-select):
  • Extract to new skill/agent — description: Author a new project-local package now (Phase 4).
  • Route to /ievo:evo — description: Hand off as a lesson — evo decides the exact overlay target.
  • Skip — description: Not worth capturing. Nothing happens to this pattern.

The proposed disposition is a suggestion, not a decision — the user can pick any option regardless of what Step 4 proposed. Wait for explicit approval before any file is created, edited, or handed off. A candidate the user skips ends there.

Phase 4: Authoring [CHECKPOINT 2]

Step 5: Option A candidates — author the package

Reuse the shared machinery in ../consolidate/references/package-authoring.md — Naming, Description, the Skill/Agent/Pair templates, Registration, and pre-checkpoint Validation all apply unchanged. The only difference from consolidate/SKILL.md's own use of that reference: set

metadata:
  source: extract-best-practices
  extracted_from: session-analysis (<ISO-8601 UTC date of this run>)
  extracted_at: <ISO-8601 UTC timestamp>

in place of consolidate's overlay-path extracted_from value — there is no single overlay file this pattern came from, it was distilled directly from the session.

Re-audit before CHECKPOINT 2 (security). Hold Registration's write until this gate clears — draft the body in context first, then audit the draft (package-authoring.md § Registration states the same audit-before-write ordering rule). Nothing is written here: in this skill CHECKPOINT 2 is what gates the write (see Anti-Pattern Detection below), so a draft that clears the re-audit is presented there and written only after that approval. That is the one ordering difference from consolidate/SKILL.md Step 8, whose item 5 writes before its own CHECKPOINT 2 (that checkpoint gates its Step 9 overlay pruning instead) — the audit-before-write guarantee itself is identical in both. The drafted body is unreviewed content headed for <project>/.claude/skills/<name>/SKILL.md or <project>/.claude/agents/<name>.md — the project's trusted, auto-dispatched-by-name-or-description directory — and the session content it was distilled from can carry attacker-influenced text (e.g. a malicious skill's SKILL.md body surfaced via /ievo:inspect//ievo:index-repos, or a crafted PR reviewed via /ievo:deep-review, engineered to be session-mined as a "repeated pattern"). Gate the draft exactly like evo/SKILL.md Step 2.5 gates a freshly vendored package, and like consolidate/SKILL.md Step 8 item 4 gates its own from-scratch authoring:

• How to audit — inline, never a sub-agent. Apply the antivirus deep-scan methodology from security-check/SKILL.md directly in this session: read that file and follow its Step 3 (threat-pattern reasoning) and Step 4 (verdict construction) against the drafted body already in hand. Do not dispatch a security-auditor sub-agent, on any platform — its § Input accepts only remote candidate identifiers (<owner>/<repo>@<skill>, <owner>/<repo>:<path>, <owner>/<repo>/<plugin>), and its Step 1 runs security-check's fetch-shaped Steps 1-2 (skills.sh lookup, gh api metadata resolution, shallow clone), none of which an unpublished local draft satisfies. A sub-agent's context isolation would buy nothing here either: this session distilled the body itself, from its own context. This matches evo/SKILL.md Step 2.5's documented inline fallback, and keeps this skill inside its declared compatibility: surface (no Task dispatch).
• GREEN → include this candidate at CHECKPOINT 2; Registration's write runs after that approval, never here.
• YELLOW or RED → do NOT write. Ask via AskUserQuestion first: <type>/<name> was flagged <verdict> on re-audit: <top 1-2 flags — category + one-line explanation>. Author it anyway? — options Author anyway (I've reviewed the flags) (carry it to CHECKPOINT 2 like a cleared candidate — its write still waits for that approval) or Discard — do not author this candidate (the candidate never reaches CHECKPOINT 2 and is never written; report the candidate as discarded, same end state as if the user had picked Option C — Skip — at CHECKPOINT 1).
• No interactive session available (headless/scheduled run — same detection as evo/SKILL.md Step 2.5), or a platform with no AskUserQuestion at all: auto-select Discard, same as an explicit decline, and note it in Phase 6's report as DISCARDED — flagged <verdict>, no interactive session to confirm.
• Never fabricate a lower verdict, and never present a YELLOW/RED candidate at CHECKPOINT 2 (and so never write it) without an explicit override (a headless run's auto-selection is always a discard, never an override). Because the audit precedes both the checkpoint and the write, a discard needs no delete — nothing reached disk, so no capability beyond this skill's declared Glob/Read/Write surface is required.

Step 6: Option B candidates — hand off to /ievo:evo

Pass the pattern's synthesized description as the lesson text — session-mined patterns have no single verbatim quote to preserve the way a user-stated correction does, so the synthesis itself is the lesson; state it plainly, don't dress it up or oversell its generality. Let evo run its own Steps 1–5.7 unchanged, including its own upstream-offer (Step 5.6) and cluster-extraction offer (Step 5.7) — this skill's job for that candidate ends at the handoff.

CHECKPOINT 2

Before any Step 5 write happens, show a diff summary: packages about to be created (exact paths — each already drafted, frontmatter-validated, and cleared through Step 5's re-audit, since a candidate discarded there never reaches this list) and evo handoffs about to run (pattern summary + evo will resolve the target). Wait for approval, then perform Registration's writes — in this skill the checkpoint, not the re-audit, is what gates the write. Same approval discipline as consolidate/SKILL.md's CHECKPOINT 2, which sits one step later in its own flow (its Step 8 has already written the package by then, so its CHECKPOINT 2 gates the Step 9 overlay pruning). A user who declines here for a given candidate leaves it untouched — nothing was written for it; already-approved-and-written candidates from an earlier batch in the same run are not rolled back.

Phase 5: Upstream sharing (Option A candidates only, optional)

After a Step 5 package write is approved and complete, decide — same lightweight heuristic style as evo/SKILL.md Step 5.6, no sub-agent dispatch — whether it's a genuinely marketplace-worthy contribution to ievo-ai/skills itself, a materially higher bar than "worth keeping in this project."

Classify upstream relevance. Default: local — and when local, do NOT prompt.

Upstream-relevant only when ALL of:

• It's an Option A package (an Option B candidate is never offered upstream here — evo's own Step 5.6 already covers upstream escalation for lessons, once handed off in Step 6).
• It contains no project-specific content — no internal tool/service names, company-specific paths, secrets, or business logic. The procedure/judgment would help any project doing this kind of work, not just this one.
• It doesn't duplicate an existing ievo-ai/skills shipped skill (re-use the Phase 2 scan if it happened to include this plugin's own skills) — a near-duplicate is a lesson on the existing skill, not a new contribution.

When in doubt, stay local — the offer is a nicety, not a gate; a false nag undercuts the "never create without user approval" discipline this whole flow exists to protect.

If local: skip straight to Phase 6. Ask nothing, submit nothing.

If upstream-relevant: offer once per candidate via AskUserQuestion (never auto-submit):

• Question: <name> looks like a genuinely reusable pattern, not specific to this project — also submit it as a contribution to the ievo-ai/skills marketplace?
• Header: Share upstream
• Options (single-select):
  • Share as feedback (Recommended) — description: Hands off to /ievo:feedback with the distilled package pre-filled as a Feature proposal. You still review and explicitly confirm before anything is posted publicly.
  • Skip — description: Keep the package local to this project. Nothing is posted.

If Skip (or the platform can't prompt / has no feedback skill available): proceed to Phase 6. Nothing is posted.

If Share as feedback: hand off to the feedback skill (/ievo:feedback) — the same pre-filled-content handoff feedback/SKILL.md Step 0 flow (C) already supports for evo/SKILL.md Step 5.6, just with a distilled package writeup instead of a one-line lesson as the pre-filled body:

• Pass a pre-filled body: a short paragraph (what the pattern is, why it generalizes, that it was distilled from a project session — no project name/path) followed by the full authored SKILL.md (and agent.md, if a pair) content in a fenced code block, verbatim from the Step 5 write.
• feedback still runs its own Step 1 (classify type — the user typically picks Feature), Step 3 (environment), Step 3.5 (clarify — usually skipped, already detailed), Step 4 (build body, flow-A format — the pre-filled text becomes <body_en>), and — critically — Step 5 (public-posting confirmation gate) unchanged. Public posting stays behind that explicit Submit/Cancel gate; this skill never posts anything itself.

Then continue to Phase 6. The locally-authored package from Step 5 already stands regardless of the upstream outcome (share, skip, or cancel at feedback's gate) — it is never deleted or altered based on what happens here.

Phase 6: Report

Patterns found:              N
Extracted (new skill/agent): <list of paths, or none>
Routed to /ievo:evo:         <list of pattern summaries, or none>
Skipped:                     <count>
Discarded on re-audit:       <list of candidate names + verdict, or none>
Shared upstream:             <list of feedback issue URLs, or "none offered" / "offered, all skipped" / "offered, cancelled at feedback gate">

Anti-Pattern Detection

Stop and reconsider if any of these hold — kept from the pattern this skill was distilled from:

• No skill/agent for a one-off task. Phase 1's threshold (seen 2x, or unambiguously general from one occurrence) exists to stop this.
• One skill = one concern. A pattern spanning multiple unrelated concerns should be split into separate candidates before CHECKPOINT 1, never authored as one bloated package.
• Never create without user approval. CHECKPOINT 1 gates disposition, CHECKPOINT 2 gates the write/handoff, Phase 5's own gate covers the upstream offer, and feedback's own Step 5 covers the actual public post — four independent gates, none skippable.
• A candidate flagged YELLOW/RED on Step 5's re-audit is written to disk or presented at CHECKPOINT 2 without an explicit override (a headless run's auto-selection is always a discard, never an override) — discard the draft instead, before Registration's write.
• Registration's write runs before Step 5's re-audit, so a flagged candidate has to be deleted rather than simply not written — the audit-before-write ordering exists precisely because this skill declares no delete capability.
• Never edit an existing skill/agent body directly. Option B routes through /ievo:evo's overlay model; this skill has no direct-edit path by design, mirroring evo/SKILL.md's own "NEVER modify the agent/skill body" rule.
• A newly authored package that fails package-authoring.md's validation checklist (name/directory mismatch, description over length, a vendor-locked model: ID) — fix before CHECKPOINT 2, never ship an invalid package.

See also

• evo/SKILL.md — Option B candidates land here (Step 6); its own Step 5.6 (upstream escalation) and Step 5.7 (cluster extraction) run independently once handed off. Its Step 5.6 pattern is what Phase 5 above mirrors for a full package instead of a one-line lesson.
• consolidate/SKILL.md — the sibling "does this generalize into a skill/agent" judgment, but triggered by already-/evo'd overlay entries (.ievo/evolution/*.md) rather than a live, un-flagged session. references/package-authoring.md is shared infrastructure between both skills.
• feedback/SKILL.md — Phase 5's upstream-sharing handoff target; its flow (C) pre-filled-content path now covers both an /ievo:evo lesson and an /ievo:extract-best-practices package writeup, public posting always behind its own Step 5 gate.
• security-check/SKILL.md — the antivirus deep-scan methodology Step 5's re-audit applies inline against the drafted body, before Registration's write; Steps 3-4 of that skill are the parts that operate on content already in hand, the same technique evo/SKILL.md Step 2.5 falls back to and consolidate/SKILL.md Step 8 item 4 uses for the identical constraint. No security-auditor sub-agent is dispatched — its § Input takes remote candidate identifiers only.
• overlay-status/SKILL.md — lists what's already captured, useful context before a mining run to avoid re-flagging something already /evo'd.