skill-refactor

Skill Refactor

Analyze skill reliability from session evidence and return prioritized recommendations.

Read when: evidence schema or audit criteria are needed: contract Read when: session history must be inventoried or extracted before synthesis: session evidence workflow

Philosophy

• Evidence first: recommendations must be traceable to concrete session artifacts.
• Favor high-leverage fixes that reduce repeated failures across multiple skills.
• Keep recommendations executable by mapping each finding to a clear next action.

When to use

• Use when the user asks for evidence-backed skill reliability analysis from session history.
• Use when deciding whether to install, improve, merge, or retire skills.

Required inputs

• A clear analysis scope (single skill, category, or full inventory).
• Session evidence sources or local artifacts available for review, preferably a ~/.agents/session-collector bundle for broad session scope.
• Ranking criteria for severity and impact.

Deliverables

• Prioritized findings with explicit evidence links or file references.
• Recommended actions grouped by keep, improve, merge, or retire.
• A short risk note for any recommendation that could remove capabilities.
• Structured output includes schema_version: 1 when requested or when automation will consume the result.

Procedure

1. Define scope: single skill, lane, or full inventory.
2. Gather evidence from session-collector bundles, session logs, skill metadata, and related references.
3. If the session scope is broad or the user references prior attempts, run or consume ~/.agents/session-collector before selecting deep dives; extract only bounded skeleton/error snippets for selected sessions.
4. Group failures by root cause (coverage gap, instruction drift, routing mismatch, or quality regression).
5. Rank recommendations by impact, confidence, and implementation cost.
6. Return a concise keep/improve/merge/retire action table with evidence anchors.