Skip to content
Skills Library
AI & agents · Analysis

skill-refactor

/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.

Licence
Apache-2.0
Last repository change
10.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/correlate_multi_source_skill_failures.py, scripts/scan_codex_sessions.py, scripts/test_session_evidence_workflow.py, scripts/test_wrappers.py

What it does and when to use it

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.

Original author description

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.

How it works

  1. Philosophy
  2. When to use
  3. Required inputs
  4. Deliverables
  5. Procedure
  6. Constraints
  7. Validation
  8. Anti-patterns
  9. Failure mode
  10. Gotchas
Original SKILL.md headings · 85 lines, 561 words
SKILL.md preview
---
name: skill-refactor
description: 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.
metadata:
  skill-type: data_fetch_analysis
---

# Skill Refactor

Analyze skill reliability from session evidence and return prioritized recommendations.

Read when: evidence schema or audit criteria are needed: [contract](./references/contract.yaml)
Read when: session history must be inventoried or extracted before synthesis: [session evidence workflow](./references/session-evidence-workflow.md)

## 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.

Reference scripts for deterministic evidence extraction:
- [scan_codex_sessions.py](./scripts/scan_codex_sessions.py)
- [correlate_multi_source_skill_failures.py](./scripts/correlate_multi_source_skill_failures.py)
- Preferred collector root: `~/.agents/session-collector`
- [session evidence workflow](./references/session-evidence-workflow.md)
- Assets: [skill-refactor.png](./assets/skill-refactor.png), [icon-small.png](./agents/assets/icon-small.png), [icon-large.png](./agents/assets/icon-large.png)

## Constraints

- Do not invent evidence or confidence ratings.
- Do not read or paste raw multi-megabyte session transcripts into context; inventory first, then extract bounded evidence.
- Do not recommend destructive skill removals without explicit impact and rollback notes.
- Redact secrets, credentials, tokens, and sensitive user content in summaries and artifacts.
- Keep analysis scoped to the requested repository or dataset.

## Validation

- Verify each recommendation cites at least one concrete artifact.
- Verify severity ordering is explicit and reproducible.
- Verify no recommendation conflicts with repository instruction hierarchy.
- Fail fast: stop at first missing or unreadable evidence source and report the exact gap.

## Anti-patterns

- Concluding "low quality" without citing failure evidence.
- Proposing merges solely on naming similarity without overlap analysis.
- Mixing unrelated tooling advice into a skill-refactor recommendation set.

## Failure mode

- If evidence sources are missing or unreadable, stop and report the exact gap.
- If scope is ambiguous, request clarification before producing recommendations.

## Gotchas

- Do not infer outcomes without evidence; mark uncertainty explicitly.
- Avoid duplicate recommendations when one root cause explains multiple symptoms.

## Examples

- "Can you inspect the last week of Codex sessions and tell me which skills to keep, improve, merge, or retire?"
- "Help me find the top three recurring skill failures from these run artifacts and suggest minimal fixes."
- "Check the sessions from this branch and tell me whether the repeated release-triage mistakes need a new reusable skill or a focused fix to an existing one."
Files in this package (15)
  • .skillignore 1 KB
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • agents/assets/icon-large.png 22 KB
  • agents/assets/icon-small.png 3 KB
  • assets/skill-refactor.png 7 KB
  • references/contract.yaml 1 KB
  • references/evals.yaml 6 KB
  • references/prompt-injection-expected-context.json 1 KB
  • references/session-evidence-workflow.md 5 KB
  • references/task-profile.json 1 KB
  • scripts/correlate_multi_source_skill_failures.py 1 KB
  • scripts/scan_codex_sessions.py 1 KB
  • scripts/test_session_evidence_workflow.py 14 KB
  • scripts/test_wrappers.py 1 KB

Versions

RepositoryScoreLicence
This page · jscraik/Agent-Skills95Apache-2.0
jscraik/Agent-Skills100Apache-2.0
kouko/monkey-skills100MIT
navapbc/digital-service-orchestra100Apache-2.0

Database snapshot: 13.11.2026 · package version a2f900f01cf4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90skill-audit
    Mine your Claude Code, Codex, pi and Cursor session history for how your skills actually get used - invocations, coverage, tool-error rates, corrections, interrupts, tokens - attributed per invocation rather than per session, then turn the aggregates into a reviewed report. Use…
  • 100evolve-skills
    Use when reviewing the skill library as a whole and driving the skill lifecycle — auditing every hub skill and overlay against usage telemetry, bench history, and lint debt to decide refine/merge/prune/create ("review the skill library", "skill lifecycle pass", "which skills…
  • 90skills-audit
    Audit agent skills for triggering quality, correctness, context efficiency, redundancy, structure, failure guidance, and coverage gaps. Use when the user asks to review, improve, compare, simplify, or evaluate skills in global, repo-local, Claude, Codex, or custom skill paths.
  • 100skill-collection-bootstrapper
    Audit a skills repository, identify coverage gaps, validate SKILL.md files, and prepare an approval-gated installation plan. Use for: bootstrap skills, complete skill collection, install skill repository, validate skill library.
  • 100skill-usage-stats
    只读统计 Claude/Codex 的 Skill 使用证据并检查 agent 配置健康。仅用于明确的健康检查、配置诊断、使用排行或低使用候选请求;会识别 enabled 插件并单列批量审计读取。哪些 skill 坏了、互相抢触发、点名却没触发、占用列表预算,或要用历史请求检验改写后的描述,改用 skill-checkup。不要用于规范源、全局/项目/profile/冷存储、投影或退役治理,改用 skill-ecosystem-doctor。忽略引用日志和相邻任务。
  • 100claude-skill-prereq-audit
    Scan skills for prerequisite tools, MCP servers, and auth requirements, then check if everything is installed and authenticated. Offers to fix issues. Use when setting up a new machine, after installing skills, or to verify your environment. Triggers: "check prerequisites",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.