CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

skill-refactor

Scan Codex session history for skill failures, usage patterns, and coverage gaps. Use when the user wants daily skill-health monitoring or evidence-backed recommendations about installing, improving, merging, or pruning skills.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, largely lean instruction skill with a clearly sequenced workflow, explicit validation checkpoints, and well-signaled one-level-deep references. Weaknesses are mild redundancy across Constraints/Validation/Failure mode/Gotchas, missing script invocation examples, and two broken asset links.

Suggestions

Deduplicate the repeated evidence-gap and evidence-invention rules (Validation/Failure mode, Constraints/Gotchas/Philosophy) into a single section, and link session-evidence-workflow.md only once, to lift conciseness from good to lean.

Add a one-line invocation example for each referenced script (e.g., the arguments scan_codex_sessions.py expects and a sample command), and show the shape of the keep/improve/merge/retire action table.

Fix the asset links: icon-small.png and icon-large.png point at ./agents/assets/, which is outside this bundle and doesn't exist; point them at the actual asset paths or drop them, and consider linking references/evals.yaml so it is discoverable.

DimensionReasoningScore

Conciseness

The body is mostly lean, imperative bullets with no explanation of concepts Claude already knows, but there is repeated material: "stop and report the exact gap" appears in both Validation ("Fail fast: stop at first missing or unreadable evidence source and report the exact gap") and Failure mode; "Do not infer outcomes without evidence" (Gotchas) restates "Do not invent evidence" (Constraints) and "Evidence first" (Philosophy); and session-evidence-workflow.md is linked twice (lines 13 and 52). Fits anchor 4 (minor trims possible), not anchor 5 where every token earns its place, and well above the verbosity of anchor 3.

4 / 5

Actionability

Concrete guidance throughout: named extraction scripts, exact collector root "~/.agents/session-collector", a bounded-snippet extraction rule, an explicit deliverable field ("schema_version: 1"), a root-cause taxonomy ("coverage gap, instruction drift, routing mismatch, or quality regression"), and ranking criteria. Minor gaps keep it below anchor 5: no invocation examples or arguments for the referenced scripts (they are thin runpy wrappers whose CLI is not shown), and the keep/improve/merge/retire action table format is described but never exemplified. Well above anchor 3, where guidance would be pseudocode or missing key details.

4 / 5

Workflow Clarity

A clear six-step Procedure with a dedicated Validation checklist ("Verify each recommendation cites at least one concrete artifact", "Verify severity ordering is explicit and reproducible"), an explicit fail-fast checkpoint on missing evidence, and error-recovery guidance in Failure mode (stop and report the gap; request clarification on ambiguous scope). The batch-operation validation cap does not apply because validation steps are present. This matches anchor 5: sequenced steps, explicit validation, feedback for error handling.

5 / 5

Progressive Disclosure

The "Read when:" signaling for references/contract.yaml and references/session-evidence-workflow.md is exemplary and one level deep (the workflow reference contains no nested file links), and the scripts are clearly listed with their purpose. Minor organization gaps keep it below anchor 5: the icon links "./agents/assets/icon-small.png" and "./agents/assets/icon-large.png" point outside the bundle and don't exist (assets/ contains only skill-refactor.png), session-evidence-workflow.md is referenced twice, and bundle materials like references/evals.yaml are never surfaced.

4 / 5

Total

17

/

20

Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description with a clear what, an explicit 'Use when...' clause, and concrete trigger phrases. Its main weaknesses are a jargon-y "daily skill-health monitoring" trigger and missing natural synonyms, plus mild overlap risk with general session-analysis skills.

DimensionReasoningScore

Specificity

"Scan Codex session history for skill failures, usage patterns, and coverage gaps" plus "recommendations about installing, improving, merging, or pruning skills" lists multiple concrete actions covering the full analysis-to-recommendation pipeline. Coverage is comprehensive for the domain, matching the anchor-5 example's structure rather than the 'several actions, minor gaps' anchor 4.

5 / 5

Completeness

Explicitly answers both questions: "Scan Codex session history for skill failures, usage patterns, and coverage gaps" states the what, and "Use when the user wants daily skill-health monitoring or evidence-backed recommendations about installing, improving, merging, or pruning skills" gives concrete trigger phrases. This matches the anchor-5 example's structure exactly; anchor 4 would require the when-clause to be less explicit.

5 / 5

Trigger Term Quality

Good natural keywords ("skill failures", "usage patterns", "coverage gaps", "session history", "installing, improving, merging, or pruning skills") but "daily skill-health monitoring" is jargon users would rarely say, and common synonyms like "audit", "clean up", or "retire/remove skills" (which the body itself uses) are absent. Clearly above anchor 3 (multiple relevant, genuinely natural terms present) but short of anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The niche (skill reliability analysis from session evidence) and lifecycle triggers are mostly distinct, but "usage patterns" and "session history" scanning could overlap with generic session/log-analysis skills, and "daily skill-health monitoring" could fire on broad monitoring requests. Minor overlap risk with closely related skills fits anchor 4; not anchor 5 because a couple of triggers are broad enough to invite misfires.

4 / 5

Total

18

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 2 missing, 2 deeper-than-1-level

Warning

Total

14

/

16

Passed

Repository

jscraik/Agent-Skills

Path

Infrastructure/references/deferred-skill-context/skill-factory-skill-refactor/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.